Where your keys live

Never in the repository

No key material ever enters the object store. Secrets do not sync. This is a hard architectural rule, not a configuration setting.

The part most people get wrong

Your private keys are not stored in the OS keychain. They live on disk under .tovio/identity/, sealed at rest with AES-256-GCM. The keychain holds only the 32-byte wrapping key those files are sealed under.

That distinction explains most of the behaviour you will meet: why a locked keychain makes reads fail with TVO-KEY-002 even though the key files are right there, why copying .tovio/ to another machine does not move your identity, and why a CI runner can work with one injected secret.

Which store holds the wrapping key

On a headless host with no credential store, inject the wrapping key instead — see Keys on a headless or CI machine.

The sealed blob is bound to its slot

A key file is bound to the account and entry name it was sealed for, so renaming or copying a .key file fails the authentication tag rather than silently substituting a different identity. If the sealed key does not derive the public key in .tovio/identity.pub, TOVIO refuses to sign or decrypt at all — TVO-KEY-007, fail-closed.

Per device

Each device has its own key. Losing a laptop means revoking one device, not rotating everything.

tovio device listtovio device revoke <did-or-name>

Inspecting

tovio identity showtovio key status

key status shows the attribute certificates you hold, with issuer, expiry and validity — worth checking before they lapse.

The thing to do today

tovio key export backup.key --passphrase-file pass.txt

A keychain is not a backup. Reinstalling an OS destroys the wrapping key, and the sealed files left behind become permanently unopenable.