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. This tutorial shows you how to link, check, and remove devices for yourself and teammates.
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
- Ghostable CLI installed.
- 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
Run the device wizard on any new workstation or rotation host.
ghostable device link
What happens: the CLI mints signing + encryption keys locally, registers the public keys with Ghostable, and stores the private keys in your OS keychain. No secrets leave your machine.
2. Verify device status
Confirm that your local keys match what Ghostable knows about this machine.
ghostable device status
You should see local fingerprints, device ID, platform, and remote status. If the device was revoked, link again to regain access.
3. Onboard a new teammate
- Add them to the organization/project with the right role.
- They run
ghostable loginthenghostable device linkon their workstation. - 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.
4. 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.
5. 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.