Skip to main content
Capy is self-custodied. Your master key never lives on the service in a form the service can use - not even the service itself can hand it to a new machine. That’s the core zero-trust guarantee, and it’s the reason switching computers looks different here than with a centralized secrets store.

​
How it’s different from a centralized store

The tradeoff is a small amount of friction when you get a new laptop, in exchange for the vendor never being a single point of compromise. If a centralized vendor gets breached, the attacker walks away with everything. If Capy’s service gets breached, the attacker walks away with ciphertext they can’t decrypt, because the decryption material lives on your machine and only your machine.

​
The transport flow

capy transport is the explicit handoff command. It mints a time-limited transport code on your current machine, which you run on your new machine to carry the organization’s master key across.
  1. On your current machine: capy transport. Capy prints a ready-to-paste capy redeem <code> command and offers to copy it - press c.
  2. On the new machine: capy redeem <code>. Capy signs you in - silently from a cached session where it can, with a browser sign-in where it can’t - asks the service to strip the outer wrap, strips the inner wrap locally, and writes the key to ~/.capy/orgs/{orgId}/users/{userId}/key.enc.
  3. The code expires - seven days after it’s minted, by default - and Capy prints the exact expiry when it mints it. The inner wrap is bound to your email address, so only the same account can open it, and the service re-checks that you’re still a member at redeem time.
The key material never reaches the service in plaintext. The code carries your master key double-wrapped: the service can strip only the outer layer, and the inner layer is keyed to the token inside the code plus your email, so neither the code alone nor the service alone is enough. A transport code covers one organization. If you belong to several, run capy transport once per org - Capy takes the org from keep.lock in the current directory, and asks you to pick one when there’s no keep.lock to read it from.

​
Alternative paths

​
Seed phrase recovery

If you’re the org owner and still have the 24-word phrase Capy printed when you created the org, re-derive the master key with capy recover.
  1. Install Capy on the new machine.
  2. Run capy recover. Capy signs you in, asks which organization the phrase belongs to, and prompts for the 24 words with masked input.
  3. Capy checks the phrase against a piece of that org’s own ciphertext, re-derives the master key locally via PBKDF2, re-wraps it for this device, and stores it at ~/.capy/orgs/{orgId}/users/{userId}/key.enc. If the org has no stored secrets yet there’s nothing to check against, so Capy says so and writes the key anyway.
capy recover always asks which org to recover, even inside a project - local state can point at the wrong org, and wrapping the key for the wrong one only fails later, confusingly. If a key for that org already exists on this device, Capy warns you and asks before overwriting it. The command still talks to the service - it signs you in, and the outer wrap on the stored key comes from the service - but the master key itself is derived from your words on your machine and never leaves it. Capy shows the phrase once, at org creation, and cannot reissue or reconstruct it, which is exactly why you write it down then.

​
Fresh invite

If you don’t have a seed phrase, ask an org admin to re-issue your invite.
  1. The admin runs capy invite your-email@example.com and sends you the capy redeem command it prints, out-of-band. Re-inviting someone who is already a member reuses their current role and project access, so nobody has to set you up again.
  2. On your new machine: capy redeem <code>.
  3. Capy installs the org’s master key on the new device.
An invite code carries the same double-wrapped key a transport code does, bound to the invited email address, and expires the same way. The admin can shorten that window with capy invite --ttl 30m or --expires <iso>.

​
Why this model

Centralized stores have a single point of trust. If they’re breached, everyone’s secrets leak. Capy distributes that trust:
  • The service holds your ciphertext and performs the outer wrap and unwrap - it never sees the master key in plaintext.
  • Your device holds the wrapped master key. Stripping its outer layer takes the service, so a stolen key.enc on its own is inert.
  • Neither side can decrypt alone. The org’s 24-word phrase is the deliberate exception: it derives the master key by itself, which is why only the owner ever sees it, and only once.
capy transport keeps that invariant when you move to a new device. Even the service mediating the handoff can’t read your key during the move: it strips the outer layer and hands back a blob that only the token inside your code can open. See Zero trust for the full threat model and Cryptography for the exact constructions.

​
What’s next

Switching organizations

Moving between orgs on a single machine.

Zero trust

Why the service can’t release your key alone.
Last modified on August 11, 2026