Skip to main content

Need the shared device model?

Read the Fundamentals page for the cross-client device model, then use this guide for CLI commands.

​
Why Devices Matter

Ghostable never sees plaintext secrets. Instead, each developer links their workstation (or CI host) as a device. Linking generates an encryption + signing keypair, stores it securely on your machine, and registers the public keys with Ghostable so the service can share environment keys with you. Every CLI operation that encrypts or decrypts secrets relies on the current device identity. If the keys are missing (or revoked), commands such as env push, env pull, or deploy will fail until you link again.
Using WSL? The OS keychain is disabled by default. Install a keyring package (sudo apt-get install gnome-keyring), restart WSL, then run ghostable login / ghostable device link. You’ll be prompted to create a “Default keyring,” which enables secure key storage inside WSL.

​
Linking a Device

Run the device wizard anytime you set up a new workstation or rotation host: 
ghostable device link
What happens:
  1. Metadata prompts – you can customize the device label and platform, or accept the hostname + OS defaults. These are visible to teammates in the dashboard.
  2. Key generation – the CLI mints signing + encryption keys locally.
  3. Registration – the public keys are uploaded to Ghostable so team members (or CI tokens) can share environment keys with this device.
  4. Persistence – the private keys are stored securely via the OS keychain / secure enclave.
Sample session: 
$ ghostable device link
? Device label (reported to Ghostable)  macbook-pro
? Platform (reported to Ghostable)  darwin-arm64 (23.4.0)
✅ Device linked successfully.
✅ Device ID: dev_01HXYZABCD123
🔑 Encryption fingerprint: 4F:2C:98:C4:7A:...

​
If Access Is Still Pending

A newly linked device might still need environment key envelopes before it can decrypt variables. In that case, Ghostable will show a pending key re-share state instead of silently failing.
  • Recipients see a waiting message in CLI/Desktop.
  • Eligible actors can fulfill from Desktop or CLI:
ghostable env reshare pending
ghostable env reshare fulfill <request-id>
ghostable device init is an alias for device link. Use whichever fits your muscle memory.
Device linking is meant for human-operated machines (laptops, workstations, bastion hosts). For CI or ephemeral runners, mint a deployment token instead via ghostable deploy token create.

​
Checking Device Status

Use device status to confirm that your local keys match what Ghostable knows about this machine: 
ghostable device status
The command shows two sections:
  • Local Device Identity – ID, label, platform, and both key fingerprints found on disk.
  • Remote Status – platform, lifecycle state (active / revoked), and timestamps for creation, last seen, and revocation.
Example output: 
Local Device Identity
ID: dev_01HXYZABCD123
Name: macbook-pro
Platform: darwin-arm64 (23.4.0)
Signing fingerprint: B7:AE:51:4C:...
Encryption fingerprint: 4F:2C:98:C4:7A:...

Remote Status
Platform: darwin-arm64
Status: active
Created: 2024-06-02 10:15:48 -0500
Last seen: 2024-06-04 12:01:10 -0500
Revoked at: n/a
If the command fails, check that you are logged in and that the .ghostable/device directory hasn’t been deleted.

​
Unlinking / Rotating a Device

When a workstation is retired (or compromised), revoke its access and delete local keys: 
ghostable device unlink
The CLI confirms before proceeding, revokes the device server-side, and removes the local key material. If the device was already deleted from Ghostable, you can still clear the local state to prevent future use.
Revoking a device immediately blocks it from decrypting secrets. Make sure any active environments, daemons, or CI jobs are migrated to a different device first.