Skip to main content

Need the shared security model?

Use Fundamentals for the shared security posture. Use this page when you specifically need the CLI backup flow.
 Ghostable backups are sealed envelopes meant for disaster recovery and vendor exit scenarios—not day‑to‑day secret distribution. Access is fixed at creation time and cannot be revoked later. Keep the resulting .gsb files and private keys offline and protected.

​
Before you start

  • You need a device with access to the target environment (it must already be a recipient of the environment key).
  • Optional: an organization recovery X25519 public key to include as a second recipient for the Backup Data Key (BDK).
  • Understand the posture: no server-side escrow, no rewrapping, and no restore-time policy checks.

​
Create a backup (online)

Run the CLI while authenticated and on a device that can read the environment key. 
ghostable backup create --env production \
  --recovery-key <BASE64_X25519_PUBLIC_KEY> \
  --recovery-label "Org Recovery"
  • The API verifies authorization, fetches the already-encrypted environment bundle, generates a one-time BDK, and envelope-encrypts that BDK to:
    • Your requesting device
    • (Optional) the supplied recovery public key
  • The CLI does not decrypt anything; it writes the returned envelope verbatim to a .gsb file (default .ghostable/backups/...gsb, which is ignored by Git).
  • Warnings shown during creation are intentional: backups are non-revocable and keys included at creation are the only ones that can ever restore.

​
Restore offline (API-free)

Restores happen locally and require a matching private key from backup creation. 
ghostable backup restore --file ./.ghostable/backups/ghostable-prod-*.gsb \
  --to-file ./restored.env \
  --recovery-private-key <BASE64_X25519_PRIVATE_KEY> # optional, if included
What happens locally:
  1. Validate the envelope format and integrity hash.
  2. Find a matching recipient:
    • Device private key stored on this machine, or
    • Provided organization recovery private key.
  3. Decrypt the BDK, then the payload, then the environment key envelope, and finally the secrets.
  4. Require an explicit output target (--to-file or --print). Nothing is exported implicitly.
  5. Zeroize sensitive material in memory and exit. No API calls are made.
If no matching private key is present, restore fails immediately—there are no retries or server-side overrides.

​
(Optional) Generate a recovery key

If you want an organization-held recovery path in case all devices are lost: 
ghostable backup keygen --out-dir ./.ghostable/keys
  • Generates an X25519 keypair locally.
  • Use the printed/public key with ghostable backup create --recovery-key <BASE64_PUB>.
  • Store the private key offline; use it on restore with --recovery-private-key or --recovery-key-file.

​
Envelope format (high level)

Backups return a JSON envelope saved as .gsb. Values below are abbreviated examples: 
{
    "version": "backup.v1",
    "backup_id": "bak_01JQ9Y6N6V3X7K8M2F4C1P9TQ",
    "project": {
        "id": "prj_01JQ9Y3R9D2J8F6M4K7T1N5PZ",
        "name": "Northstar API",
        "slug": "northstar-api"
    },
    "environment": { "id": "env_01JQ9Y52H4M8P6T1C7R3D9V2K", "name": "production" },
    "payload": {
        "ciphertext_b64": "9C7d2Lk4...==",
        "nonce_b64": "M2q8w1s4...==",
        "aad_b64": "f7L0m9Qx...==",
        "alg": "xchacha20-poly1305"
    },
    "recipients": [
        { "type": "device", "id": "dev_01JQ9Y5Y8N6C3R1T4M7K2P8DZ", "edek_b64": "q83v3v9y...==" },
        { "type": "recovery", "id": "organization-recovery", "edek_b64": "H4Z9j1Qp...==" }
    ],
    "integrity": { "sha256_b64": "pQv6XgX2...=" },
    "environment_key_fingerprint": "b8b9c2f1d0e3a7f4"
}
The encrypted payload contains:
  • bundle: The encrypted environment projection (secrets stay encrypted under the environment key).
  • meta: Backup identifiers (project, environment, backup_id, created_at).
Only the recipients listed can decrypt the BDK, and the environment key access captured at backup time determines who can actually read the secrets.

​
Operational notes

  • Backups are rare, deliberate artifacts—store them offline with corresponding private keys.
  • Adding users later does not grant access to existing backups; removing users does not revoke access.
  • There is no server-side escrow or rewrapping; if keys are lost, the backup is irrecoverable.
  • Ghostable remains the system of record; backups are for last-resort recovery and vendor exit assurance.