Ghostable is zero-knowledge: every secret is encrypted with keys that live on your device. Linking registers your workstation so Ghostable can share environment keys with it, and unlinking revokes those keys instantly. If you are on a Mac, start with Ghostable Desktop for macOS. Use the CLI when you are on Linux, Windows, or deliberately working in the terminal.
Why devices matter
- Encryption keys live in your OS keychain; Ghostable never sees plaintext env values.
- Only linked devices (or deploy tokens) can decrypt environment data.
- Revoking a device immediately cuts off access without rotating every secret.
- New teammates must link to receive shared environment keys.
Prerequisites
- A Ghostable account with access to the organization or project you need.
- On macOS: Ghostable Desktop for macOS.
- On Linux, Windows, or terminal-first setups: Node.js plus the Ghostable CLI.
- Logged in with an account that has access to the organization/project.
- OS keychain available (on WSL, install a keyring package before linking).
1. Link your device in Ghostable Desktop
On a Mac, the desktop client is the default path. Download Ghostable Desktop for macOS, sign in with your account, and complete the device-linking flow in the app.
- Install and open Ghostable Desktop.
- Sign in with the same account you use in the web app.
- Complete the trusted-device registration flow for this machine.
- Return to Ghostable and confirm encrypted workspace access is unlocked.
What happens: Ghostable Desktop creates signing and encryption keys locally in the macOS keychain, registers the public keys with Ghostable, and keeps the private keys on your machine.
For the full desktop walkthrough, read the desktop device-linking docs.
2. Use the CLI when desktop is not the path
If you are on Linux, Windows, or prefer to link from the terminal, install the CLI and sign in there instead.
npm install @ghostable/cli@latest
npx ghostable login
What happens: the CLI mints signing and encryption keys locally, registers the public keys with Ghostable, and stores the private keys in your OS keychain. No secrets leave your machine.
3. Verify device status
After linking, encrypted workspace access should unlock automatically. If you want to confirm from the terminal that local keys match what Ghostable expects for this machine, run:
ghostable device status
You should see local fingerprints, device ID, platform, and remote status. If the device was revoked, link again to regain access.
4. Onboard a new teammate
- Add them to the organization/project with the right role.
- If they are on a Mac, have them start with Ghostable Desktop. If they are on Linux, Windows, or terminal-first, have them run
npx ghostable login. - Ghostable shares environment keys to their newly linked device; they can now pull and decrypt envs.
Tip: ask new teammates to run ghostable device status and a quick ghostable env pull to confirm access.
5. Unlink and rotate on departure
When someone leaves or a laptop is compromised, revoke the device and clear local keys.
ghostable device unlink
This deletes local key material and revokes the device server-side. Ghostable re-shares environment keys to remaining devices, so the revoked machine can no longer decrypt secrets. For sensitive environments, follow with targeted secret rotation.
6. Keep CI and tokens separate
CI runners should use deploy tokens, not human device identities. Devices are for people; tokens are scoped to specific environments and can be rotated independently.
# create and use a deploy token instead of linking the CI host
ghostable deploy token create --env production --name "github-actions"
What not to do
- Do not share one linked device across multiple people or machines.
- Do not skip unlinking when hardware is lost or a teammate leaves.
- Do not rely on API login alone; without a linked device, decryption will fail.
- Do not use personal tokens in CI; prefer deploy tokens or service accounts.
Next steps
- Audit devices in the dashboard and prune stale entries regularly.
- Pair device linking with validation so env changes are checked before deploys.
- Read the devices guide and deploy token guide for deeper policy options.