Product

Three rules matter up front:

• Alpha keys are shared between devices and users out of band, not by OmegaSafe Cloud or the OmegaSafe API. The system does not upload, distribute, recover, or escrow Alpha key material.
• The server is contacted sporadically. OmegaSafe CLI is designed around local work, in-advance claim caching, and offline emergency buffers kept ahead of actual local usage.
• With Bring Your Own Storage, you retain direct control over encrypted Delta key files. If OmegaSafe Cloud became permanently unavailable, users who already have local Alpha, local key linkage, and trusted BYOS Delta files can use emergency OmegaSafe CLI recovery features to import those Deltas directly for decryption. See OmegaSafe CLI — import-key-delta.

In simple terms: OmegaSafe CLI creates and uses the encryption keys locally. The server coordinates safe use of those keys across your devices and between users by synchronizing claims on key sections, managing user sharing permissions, and helping authorized clients move encrypted Deltas. The server does not need your Alpha key to do that.

1. What The Product Is

#

OmegaSafe CLI runs on your device. It creates keys, encrypts and decrypts files, keeps local key/cache state, and connects to an External Claims Storage backend when synchronization is needed. See OmegaSafe CLI — Command Reference.

OmegaSafe API is the server side. Today, the available server option is OmegaSafe Cloud. It acts as HTTP ECS for key registration, claim synchronization, Delta listing/upload/download flows, API keys, and key sharing. See OmegaSafe API — Base URL.

OmegaSafe Self-Hosted is under development and is not available yet. See Self-Hosted — Current Status.

2. High-Level Design

#

flowchart TB
    subgraph DeviceA["Device A: key owner"]
        CLIA["OmegaSafe CLI"]
        AlphaA["Alpha key
local only"]
        CacheA["Local claim cache
performance + offline"]
        CLIA -->|"create-key"| AlphaA
        CLIA -->|"keep ahead"| CacheA
    end

    subgraph API["OmegaSafe API / HTTP ECS"]
        Metadata["Key metadata
claim state"]
        Sharing["User-to-key relations
invitations"]
        URLs["Presigned Delta URLs"]
        Metadata --- Sharing
    end

    subgraph Storage["Delta storage"]
        Deltas["Encrypted Deltas
encrypted by Alpha"]
    end

    subgraph DeviceB["Device B: same user"]
        CLIB["OmegaSafe CLI"]
        AlphaB["Alpha key
imported locally"]
        CLIB -->|"import Alpha"| AlphaB
    end

    subgraph OtherUser["Another user"]
        CLIC["OmegaSafe CLI"]
        AlphaC["Alpha key
imported locally"]
        CLIC -->|"import Alpha"| AlphaC
    end

    CLIA ==>|"register key
claim sync"| Metadata
    CLIA ==>|"request Delta
upload URL"| URLs
    CLIA ==>|"direct encrypted
Delta upload"| Deltas

    CLIB -->|"same user's API key
no invitation"| Metadata
    CLIB -->|"request Delta
download URL"| URLs
    Deltas -->|"pull encrypted Deltas"| CLIB

    Sharing -->|"invitation creates
user-key relation"| CLIC
    CLIC -->|"own API key
after invitation"| Metadata
    CLIC -->|"request Delta
download URL"| URLs
    Deltas -->|"pull encrypted Deltas"| CLIC

    AlphaA -. "out-of-band Alpha transfer" .-> AlphaB
    AlphaA -. "out-of-band Alpha transfer" .-> AlphaC

    classDef cli fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#172554;
    classDef alpha fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#450a0a;
    classDef cache fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#451a03;
    classDef api fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#052e16;
    classDef sharing fill:#ffe4e6,stroke:#e11d48,stroke-width:2px,color:#4c0519;
    classDef storage fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#2e1065;

    class CLIA,CLIB,CLIC cli;
    class AlphaA,AlphaB,AlphaC alpha;
    class CacheA cache;
    class Metadata,URLs api;
    class Sharing sharing;
    class Deltas storage;

    style DeviceA fill:#eff6ff,stroke:#60a5fa,color:#172554;
    style DeviceB fill:#eff6ff,stroke:#60a5fa,color:#172554;
    style OtherUser fill:#fff1f2,stroke:#fb7185,color:#4c0519;
    style API fill:#f0fdf4,stroke:#22c55e,color:#052e16;
    style Storage fill:#f5f3ff,stroke:#8b5cf6,color:#2e1065;

    linkStyle 0 stroke:#dc2626,stroke-width:2px;
    linkStyle 1 stroke:#d97706,stroke-width:2px;
    linkStyle 2 stroke:#16a34a,stroke-width:2px;
    linkStyle 3 stroke:#dc2626,stroke-width:2px;
    linkStyle 4 stroke:#dc2626,stroke-width:2px;
    linkStyle 5 stroke:#16a34a,stroke-width:3px;
    linkStyle 6 stroke:#16a34a,stroke-width:3px;
    linkStyle 7 stroke:#7c3aed,stroke-width:3px;
    linkStyle 8 stroke:#16a34a,stroke-width:2px;
    linkStyle 9 stroke:#16a34a,stroke-width:2px;
    linkStyle 10 stroke:#7c3aed,stroke-width:2px;
    linkStyle 11 stroke:#e11d48,stroke-width:2px;
    linkStyle 12 stroke:#16a34a,stroke-width:2px;
    linkStyle 13 stroke:#16a34a,stroke-width:2px;
    linkStyle 14 stroke:#7c3aed,stroke-width:2px;
    linkStyle 15 stroke:#dc2626,stroke-width:2px;
    linkStyle 16 stroke:#dc2626,stroke-width:2px;

The important split is intentional:

• Alpha stays local and must be transferred by your own approved process.
• Deltas are encrypted by Alpha before storage.
• Deltas can be synchronized through OmegaSafe Cloud or user-provided storage, but they are not usable without the matching local Alpha.
• Key registration on the server exists to coordinate claims, Delta synchronization, and user-to-key sharing. The OmegaSafe API has no “device” object.

For the detailed cryptographic model, see Encryption Method — Alpha and Delta Split and Encryption Method — External Claims Storage.

3. Local-First Operation

#

flowchart TD
    Start["Encrypt or decrypt request"] --> LocalReady{"Local Delta and
local claim available?"}
    LocalReady -->|Yes| LocalRun["Run locally
no server call"]
    LocalReady -->|No| Contact["Contact OmegaSafe API
only when needed"]
    Contact --> Sync["Pull missing encrypted Deltas
or reserve claim capacity"]
    Sync --> TopUp["Top up performance cache
and offline buffer"]
    TopUp --> LocalRun
    Contact -->|Unavailable| Offline{"Offline buffer
can satisfy request?"}
    Offline -->|Yes| LocalRun
    Offline -->|No| Wait["Wait for connectivity
or use documented recovery flow"]

The normal path is not constant server chatter. OmegaSafe CLI first uses local PERFORMANCE cache. When it does need the server, it claims in chunks and can also top up OFFLINE capacity. If the server is unavailable later, the CLI can continue while the local OFFLINE buffer can satisfy the request.

For the complete decision graph and exact edge cases, see OmegaSafe CLI — End-to-End Claim Decision Flow and OmegaSafe CLI — OFFLINE Cache.

4. Devices And User Sharing

#

The OmegaSafe API models users, keys, user-to-key relations, claims, Deltas, and storages. It does not model devices. That means one user can use as many devices as they want without creating invitations between those devices.

For another device owned by the same user:

1. Configure OmegaSafe CLI on that device with an API key created in OmegaSafe Cloud.
2. Transfer the Alpha out of band, then import it locally on that device.

For sharing with a different user:

1. Use the invitation flow to create that user’s server-side key relation.
2. Transfer the Alpha out of band, then have the recipient import it locally with their own OmegaSafe API access.

The invitation flow is for sharing with different users. It does not place Alpha on the recipient device. That is by design. See Keys Management — Key Sharing Model and Keys Management — Alpha Distribution Requirement.

For storage control, OmegaSafe can use OmegaSafe-managed internal storage or your own S3/R2 bucket for Deltas. See Bring Your Own Storage — Recommendation and Bring Your Own Storage — Object Layout.

5. Start Here

#

Use Quick Start — Register and Activate Your Account to create an account, download OmegaSafe CLI, connect it to OmegaSafe Cloud, create your first key, and encrypt your first file.