Switching computers

Documentation Index

Fetch the complete documentation index at: https://docs.capy.sc/llms.txt

Use this file to discover all available pages before exploring further.

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 short-lived, one-time transport code on your current machine, which you enter on your new machine to pull your identity across.

1. On your current machine: capy transport. Capy prints a short one-time code.
2. On the new machine: capy redeem <code>. Capy authenticates you, pulls your wrapped master key across, and installs it.
3. The code is one-shot and short-lived - a stolen code can’t be replayed.

The key material itself never traverses the service in plaintext. Only a wrapped blob moves, and the transport code is the material the new machine needs to unwrap it locally.

​

Alternative paths

​

Seed phrase recovery

If you’re the org owner and have your seed phrase, re-derive the master key directly.

1. Install Capy on the new machine.
2. Run capy in a project you own. When prompted, choose “recover from seed phrase” and enter your 24 words.
3. Capy 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.

The seed phrase is the only way to regenerate the master key without the service’s help, which is exactly why you write it down when you first create the org.

​

Fresh invite

If you don’t have a seed phrase, ask an org admin to send you a new capy invite code.

1. Admin runs capy invite your-email@example.com, sends you the one-time code out-of-band.
2. On your new machine: capy redeem <code>.
3. Capy installs your master key on the new device.

​

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 ciphertext and an outer wrap - useless without the inner wrap on your machine.
• Your machine holds the inner wrap and, for owners, the seed phrase - useless without the service’s cooperation to strip the outer wrap.
• No single party can decrypt alone.

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, because only your authenticated device can finish the unwrap. See Zero trust for the full threat model and Cryptography for the exact constructions.

​

What’s next