ak-vaultby AgentKit
Protocol v1 · in security review

Your secrets sync. The server only sees ciphertext.

ak-vault is the opt-in, end-to-end encrypted sync layer for ak secrets. Values are sealed on your device before they leave it, resolve never waits on the network, and with sync off the CLI makes zero network requests.

Read the security model Protocol spec on GitHub

Cloud sync is not generally available. The production sync API stays behind a kill switch until an independent security review signs off. Do not put production credentials in it yet. Local ak secrets works today without it.

one secret, two viewsillustrative
On your deviceplaintext · local only
name        OPENAI_API_KEY
value       sk-proj-xxxxxxxxxxxxxxxx
meta        "Billing project key"
sensitivity high # fresh approval
What the Worker storesciphertext + metadata
{"item_id":"q7N2fXk0RZ1hTqLw9bYc4A",
 "base_revision":7, "key_epoch":1,
 "env":{"alg":"xc20p",
   "n":"u3Rk9QeZ2vP0aL8m…",
   "ct":"Hq9Zx2LmVb0Rk7TnYc4W…"},
 "sig":"Zk3…"}
The name, value, description and sensitivity are inside ct. The Worker sees random IDs, revisions, sizes and signatures. It never holds a key that opens them.
How it works

Encrypt on the device. Relay ciphertext. Verify before you trust it.

Your local vault stays the source of truth. Sync is an extra, optional path between devices you have enrolled.

  1. Device A · ak CLI / Desktop

    You set a secret

    ak secrets set writes to the OS keychain or the age-encrypted file vault, exactly as it does today. Nothing leaves the machine unless sync is enabled.

  2. Device A · local crypto

    It is sealed locally

    Name, value and metadata are encrypted with XChaCha20-Poly1305 under a per-item key derived from the vault key, then the record is signed with the device's Ed25519 key.

  3. Cloudflare Worker · per-vault Durable Object

    The Worker stores ciphertext

    It checks the device-bound token and proof, applies the write only if the revision matches (compare-and-swap), and keeps conflicts and tombstones. It cannot decrypt.

  4. Device B · enrolled device

    Another device verifies, then decrypts

    Device B checks signatures, the owner-signed membership chain and its last witnessed checkpoint, refuses rollbacks, and only then decrypts into its own local vault.

Cross-device updates are targeted to arrive within about a minute only when both devices run an active sync service and the network works. A CLI without a background service syncs on its next invocation. Reads through resolve always come from the local vault.

Guarantees & limitations

What the design promises, and what it can't.

These are design properties of protocol v1 as proposed. They hold only once the implementation passes the security gate in issue #8.

Guarantees

  • Client-side encryption of everything sensitiveValues, names, descriptions, tags, profiles, portable policy and audit entries are encrypted before upload. spec §3.2, §7
  • Local-first resolveresolve reads the local vault and is never blocked by Worker downtime.
  • Sync off means no trafficWithout ak login and an explicit sync enable, the CLI makes zero network requests for secrets.
  • No silent overwritesRevision compare-and-swap; a stale write gets 409 and is preserved as a conflict branch to resolve explicitly. spec §5
  • Deleted stays deletedTombstones stop a stale offline device from resurrecting a removed secret.
  • Owner-signed membershipA hash-chained, owner-signed log decides which devices get the vault key. Injected recipients are rejected. spec §4
  • Rollback detectionDevices keep signed checkpoints and refuse any server state older than one they already witnessed. spec §6
  • Device-bound access, live revocationES256 tokens plus a per-request device signature; revoked sessions and devices are checked on every request and fail closed. spec §9
  • Policy can only restrictSynced policy narrows local grants; it never grants access on its own. spec §8

Limitations

  • Vault-wide key, no per-secret accessAnyone holding a vault's key can decrypt every item in it. In a shared vault you cannot restrict one member to one secret; use separate vaults instead.
  • Withheld updatesA malicious server can hide updates that a new or long-offline device has never seen. Detection needs a second channel, such as another device's checkpoint.
  • Plaintext reaches the child processak secrets run deliberately hands the value to the approved process. The vault organises and audits access; it does not seal a value away from a program you granted it to.
  • No claw-backRemoving a member or device blocks new keys and ciphertext, but anything already decrypted stays exposed. Affected secrets are marked to rotate.
  • Metadata is visibleThe server sees random IDs, revisions, sizes, timestamps, device public keys and membership. See the table below.
  • Lose every key, lose the vaultWithout an enrolled device, your master password or your recovery key, nobody can decrypt the vault, including AgentKit.
  • Not yet reviewedProtocol v1 is a proposal. Treat every property here as a design target until the external review signs off.
What the server can see

A short, explicit list of what leaves your device.

The Worker and its per-vault SQLite Durable Object hold ciphertext and the operational metadata needed to order, authorize and rate-limit writes.

Data classification for a synced vault (protocol v1, proposed)
DataServer accessNotes
Secret valuesencryptedInside the AEAD ciphertext; never in logs, errors or telemetry.
Secret names, descriptions, tags, profilesencryptedItem IDs are random, never derived from names.
Portable policy and audit entriesencryptedAudit is a hash-chained, encrypted stream.
Vault keywrappedStored only wrapped to member devices, your password-derived key and your recovery key.
Vault and item IDs, revisions, tombstone flagsvisibleNeeded for compare-and-swap ordering and conflict handling.
Ciphertext sizes and timestampsvisibleReveals roughly how many items change and when.
Devices, public keys, roles, accountvisibleThe signed membership log is readable so the server can authorize requests.
Request metadatavisibleAs with any HTTPS service, the edge sees IP address and request timing.
Master password, recovery key, device private keysnever sentThey never leave your devices.
Developer quickstart

Start local today. Sync arrives later.

The local vault ships in the AgentKit CLI now. The sync and agent-discovery commands are planned and are not available yet.

availablelocal vault v1 
# store a value (prompted, never echoed)
$ ak secrets set OPENAI_API_KEY
# see what is stored, never the value
$ ak secrets list
# agents reference it as ${secret:OPENAI_API_KEY}
plannedsync + agent profile 
# PLANNED: not available yet; syntax may change
$ ak login
$ ak secrets sync enable
# agent-friendly discovery: metadata only, never values
$ ak secrets search openai
$ ak secrets describe OPENAI_API_KEY
# ask the operator, then release to one child process
$ ak secrets request OPENAI_API_KEY
$ ak secrets run …

About run: it is the one command that intentionally releases plaintext, to the approved child process only. search and describe return metadata and never values. Shared descriptions and profiles are treated as untrusted data, never as instructions.

Architecture

Small server, strong clients.

All cryptography happens in clients that use audited libraries. The server orders, authorizes and stores. No custom cryptography anywhere.

agentkit · CLI & Desktop

Clients

  • Device signing and exchange keys
  • Encrypt, sign, verify, decrypt
  • Local vault stays authoritative
ak-vault · this project

Cloudflare Worker

  • Token, device proof and revocation checks
  • Versioned protocol and test vectors
  • Kill switch until review sign-off
ak-vault · storage

Durable Object per vault

  • SQLite-backed, one per vault
  • CAS revisions, conflicts, tombstones
  • Ciphertext and minimal metadata
ak-web · accounts

Login & dashboard

  • OAuth and device-bound tokens
  • Revocation feed to the Worker
  • Metadata-only dashboard; the browser never decrypts
Encryption
XChaCha20-Poly1305
Signatures
Ed25519
Key agreement
X25519
Key derivation
HKDF-SHA256
Password KDF
Argon2id
Server tokens
ES256 JWT
Roadmap

Built in the open, gated by review.

Work is tracked in the epic, issue #1. Personal-vault sync comes first; shared vaults, CI identities and policy follow once it is stable. No dates are promised.

  1. #2
    Protocol v1: ADR, threat model, cryptography, recovery and anti-rollback
    P0first dependency
  2. #4
    Cloudflare Worker and SQLite Durable Object: encrypted records, CAS and tombstones
    P0needs #2
  3. #5
    Shared vaults: roles, signed membership and safe rekey on removal
    P1after personal sync
  4. #6
    Machine identities: read-only CI secrets and workload revocation
    P1after personal sync
  5. #7
    Portable policy and encrypted audit, with strict device-local grants
    P1after personal sync
  6. #8
    Security validation and staged release gates: red team, performance, rollback, cost
    P0 · required for general availability
FAQ

Questions worth asking a secrets product.

Can I use cloud sync today?

No. Protocol v1 is proposed and in security review, and the production sync API is behind a kill switch until an independent review signs off (#8). The local ak secrets vault works today.

Can AgentKit read my secrets?

The design says no: the server stores ciphertext and wrapped keys only, and never receives your master password, recovery key or device private keys. It can see the metadata listed under What the server can see. Treat this as a design claim until the review completes.

What happens if the server is down?

Nothing changes for running agents. resolve reads the local vault and never waits on the network. Changes made while offline sync on the next successful connection; conflicting edits are preserved for you to resolve.

Does anything call home if I don't enable sync?

No. Sync is opt-in through ak login and an explicit sync enable. With sync off, secrets cause zero network requests, and that is part of the release acceptance criteria.

Can I give a teammate access to just one secret?

Not within one vault. A vault key decrypts every item in the vault, so v1 makes no per-secret access claim. Put the secrets you want to share in a separate shared vault. Shared vaults are planned (#5).

What if I lose my laptop?

Revoke the device. Revocation is checked on every request, so a revoked device or session is refused new reads and writes. Anything that device already decrypted cannot be clawed back, so rotate sensitive credentials. You can restore access on a new device from another enrolled device or with your master password or recovery key.

Is it open source? What does it cost?

The protocol, test vectors and Worker live in bestagentkits/ak-vault under the MIT license. No pricing has been announced.

Reading this with an AI assistant? Grab the Markdown version, or open it straight in your assistant.

Open in ChatGPT Open in Claude