Custos

How it works

In service mode, your agent is never handed your secrets.

Only on an account that can't become root; new installs start in dev mode, where an agent running as you can copy Custos's keys. How to switch

The closer to the centre, the more a part can see. Select any part to see what it can see.

Not Custos. In dev mode (today's default) it can reach Custos's keys.Your AIagentWorks today. In dev mode (today's default) it can reach Custos's keys.The agent'splug-inWorks today.Command lineWorks today, with limits. In dev mode (today's default) it can reach Custos's keys.Mac appWorks today. Has a lower-security option.Custos onyour computerPlanned.Stand-inkeysPlannedPlanned.Touch IDon your MacPlannedWorks today.Our relayWorks today, with limits.Apple,Google pushWorks today. Has a lower-security option.Approverweb appWorks today, with limits.iPhone appWorks today, with limits.Android appNot Custos.GitHub, OpenAIand othersWorks today, with limits.1PasswordWorks today, with limits.AzureKey Vault
How to read the map
  • Works today
  • Not built yet
  • Amber: a dev-mode risk or a lower-security option
More symbols
  • Works today, with a limit (the part says which)
  • Square corners: services you already use, not part of Custos
  • Amber outline: reaches Custos's keys in dev mode, today's default
  • Amber sign: has a lower-security option
Sees only names and times Your AI agent · The agent's plug-in and Mac app

Works with names, times and counts. In service mode none of these parts is given a value, sealed or clear, unless you choose an option that hands one over.

Your computer

Your AI agentThe agent's plug-inMac app
Carries locked boxes Our relay · Apple, Google push and 2 more · 1 planned

Passes on sealed data it cannot open, plus names and times.

Your computer

Touch ID on your MacPlanned

The internet

Our relayApple, Google push

Your approver devices

iPhone appAndroid app
Can see a secret Command line · Custos on your computer and 4 more · 1 planned

Handles a secret value at some point. Each part says exactly when.

Your computer

Command lineCustos on your computerStand-in keysPlanned

Your approver devices

Approver web app

Services you already use

GitHub, OpenAI and others1PasswordAzure Key Vault

Your secret

Locked by a key cut in two: one half on your computer, one with your approvers. The halves are joined only after you approve.

Works today

  • Web APIs that take the key in one header

Not yet

  • SSH keys
  • Databases
  • AWS request signing
  • Docker login
  • Tools that read a key from the environment

Limits

  • Works today
  • Not built yet
  • Amber: a dev-mode risk or a lower-security option
More symbols
  • Works today, with a limit (the part says which)
  • Square corners: services you already use, not part of Custos
  • Amber outline: reaches Custos's keys in dev mode, today's default
  • Amber sign: has a lower-security option

Each secret is locked. Its unlock key is cut in two.

One half of the unlock key stays with Custos on your computer, the other with your approvers. Neither half opens anything alone. Custos joins them only after you approve, and only for what you approved.

Follow one request

Step through what happens when your agent needs a secret. The approval you give covers one use by default, so the next call asks again. If your agent asked for longer, you can approve a longer grant, never more than it asked for, and calls that fit it go through without asking.

Your agent uses a key

  1. Your agent asks to call GitHub with your GitHub token, and says why.

    Involved Your AI agent → The agent's plug-in

  2. Custos checks the address is one you allowed for this key.

    Involved The agent's plug-in → Custos on your computer

  3. There is no approval yet, so Custos sends a locked question.

    Involved Custos on your computer → Our relay

  4. Your phone gets a ping that says only: something is waiting.

    Involved Our relay → Apple, Google pushApple, Google push → Approver web appApple, Google push → iPhone appApple, Google push → Android app

  5. You look and approve on your phone.

    Involved Our relay → Approver web app

    Sample Simplified, with made-up values; “Reported by the host, not verified” is folded below. A real request appears only in the approver you enrolled.

    Dev mode: any program running as the user on this host could have made this request and can receive released values

    work-laptop wants github-token

    Verified (in dev mode: the key and hosts, not who sent it)

    work-laptop dev mode

    github-token

    • api.github.com

    Request mapleorbittide

    The same 3 words on your terminal show that the relay did not swap the request. They do not show that you asked: your agent works in that terminal too. Different words? Tap “This wasn’t me”.

    Agent says:

    “Open a pull request for the login fix.”

    One use, within 10–15 min

    (Face ID, fingerprint or passcode)

    More about this card

    The real card heads this part “Verified”, under the red banner. The key name, its badge and the allowed hosts come from rules you signed on the approver, so they hold. The request itself is signed with the computer's key, and in dev mode any program running as you can copy that key, so the card cannot show who sent it: check the key and the agent's reason, and deny anything you did not start.

    Reported by the host, not verified

    Program
    Claude Code

    Preselected: the narrowest. The real picker labels it “Once · 10 min” or “Once · 15 min”. “This wasn’t me” is for a request you did not start.

    You hold, then confirm with Face ID, fingerprint or passcode. About the passcode

    After you switch to service mode, on an account that can't become root, the red banner goes, the computer's badge says service mode and this part is headed “Verified” alone: the facts in it then also show that you or your agent asked. Verified shows where a request comes from, not that you started it: approve only what you started.

    How often will I be asked? Only when no approval you already gave fits the call. The preselected one covers one use within 10–15 minutes, so the next call asks again. If the agent asked for longer (a lease), the card also offers longer grants (15 min, 1 h, Until …), never more than it asked for or your rules allow; keys marked tier 2, the default for prod and custom environments, allow once only.

  6. Custos checks your answer is not wider than the question.

    Involved Custos on your computer → Our relay

  7. Custos writes the use in the log, then adds the key to the request.

    Involved Custos on your computer → GitHub, OpenAI and others

  8. Your agent gets GitHub's answer, not the key. Hiding the key in the answer is a safety net.

    Involved The agent's plug-in → Custos on your computerYour AI agent → The agent's plug-in

You approve on your phone

  1. Tap the ping to open Custos.

    Involved Apple, Google push → Approver web app

  2. You see which computer asks, for which key, where it will go, and the agent's reason.

    Involved Approver web app

    Sample Simplified, with made-up values; “Reported by the host, not verified” is folded below. A real request appears only in the approver you enrolled.

    Dev mode: any program running as the user on this host could have made this request and can receive released values

    work-laptop wants github-token

    Verified (in dev mode: the key and hosts, not who sent it)

    work-laptop dev mode

    github-token

    • api.github.com

    Request mapleorbittide

    The same 3 words on your terminal show that the relay did not swap the request. They do not show that you asked: your agent works in that terminal too. Different words? Tap “This wasn’t me”.

    Agent says:

    “Open a pull request for the login fix.”

    One use, within 10–15 min

    (Face ID, fingerprint or passcode)

    More about this card

    The real card heads this part “Verified”, under the red banner. The key name, its badge and the allowed hosts come from rules you signed on the approver, so they hold. The request itself is signed with the computer's key, and in dev mode any program running as you can copy that key, so the card cannot show who sent it: check the key and the agent's reason, and deny anything you did not start.

    Reported by the host, not verified

    Program
    Claude Code

    Preselected: the narrowest. The real picker labels it “Once · 10 min” or “Once · 15 min”. “This wasn’t me” is for a request you did not start.

    You hold, then confirm with Face ID, fingerprint or passcode. About the passcode

    After you switch to service mode, on an account that can't become root, the red banner goes, the computer's badge says service mode and this part is headed “Verified” alone: the facts in it then also show that you or your agent asked. Verified shows where a request comes from, not that you started it: approve only what you started.

    How often will I be asked? Only when no approval you already gave fits the call. The preselected one covers one use within 10–15 minutes, so the next call asks again. If the agent asked for longer (a lease), the card also offers longer grants (15 min, 1 h, Until …), never more than it asked for or your rules allow; keys marked tier 2, the default for prod and custom environments, allow once only.

  3. The smallest approval is already selected: once.

    Involved Approver web app

  4. Hold, then confirm with your face, finger or passcode.

    Involved Approver web app

  5. Being built: the phone apps will accept only your face or finger.Being built

    Involved iPhone appAndroid app

  6. Your answer goes back in a box only that one request can open.

    Involved Our relay → Approver web app

  7. When your approval runs out, Custos on that computer forgets your secret and your phone's half of its unlock key.

    Involved Custos on your computer → Our relay

You add a computer or a phone

  1. You say what you are adding: a computer or a phone.

    Involved Approver web app

  2. Adding a computer: it shows a short code and you type it on your phone. Adding a phone: your current phone shows the code; type it only into the new phone, never into a chat or an AI agent.

    Involved Command line → Custos on your computer

  3. Both screens show the same six words. You check they match.

    Involved Custos on your computer → Our relayOur relay → Approver web app

  4. Your phone signs the new device in. Every device sees it in the log.

    Involved Our relay → Approver web app

  5. Pairing by scanning a QR code is being built.Being built

    Involved Custos on your computeriPhone appAndroid app

Something looks wrong

  1. Tap 'This wasn't me': that computer gets no more approvals, every approval on all your computers ends, and Custos shows which keys to change: anything already released to a compromised computer must be rotated.

    Involved Our relay → Approver web app

  2. Custos on that computer stops using your keys within a minute, or at most 3 minutes if the relay delays your revocation. A relay that shows your computers a different history can hide it for longer: type the 4 words your phone shows into a command on that computer, and Custos there locks itself if they differ.

    Involved Custos on your computer → Our relay

  3. You can also lock Custos on the computer itself, with or without your phone.

    Involved Mac app → Custos on your computer

  4. In service mode, unlocking needs your password for sudo; if your account has passwordless sudo, an agent could unlock it too. In dev mode, an agent on that computer could unlock it.

    Involved Custos on your computer

  5. Unlocking from your phone is planned.Planned

    Involved Our relay → iPhone appOur relay → Android app

Your vault stays your vault

  1. Custos stores the vault credential you create for it (a 1Password service-account token or an Azure service principal's client secret: an app's key, not your own password; custos bridge setup shows how to make it read-only, Custos does not check), encrypted like any other secret: unlocking it needs a half from your phone.

    Involved Custos on your computer

  2. After you approve, Custos fetches one item and forgets the vault credential again.

    Involved Custos on your computer → 1PasswordCustos on your computer → Azure Key Vault

  3. The item is used like any other key: your agent never sees it.

    Involved Custos on your computer → GitHub, OpenAI and others

  4. Vault bridges run only when Custos is separated from your agent; on a Mac, the 1Password bridge is the exception for now (dev mode only).

    Involved Custos on your computer

Where Custos trades security for convenience

Our rule: every option that trades security for convenience tells you the risk, asks for your OK and logs your choice; this is how far that is built today.

How far the rule is built, across all 13 options
Tells you the riskPartly for 9 of 13; fully for none
Asks for your OKFully for 1, partly for 1 of 13
Logs your choicePartly for 6 of 13; fully for none

What Custos does not protect against

Said plainly, from the same model that draws the map.

  • In dev mode, today's default install, an agent running as you can reach Custos's keys. What changes, and how to switch
  • Today only web APIs that take the key in one header. SSH keys, databases, AWS request signing, docker login and tools that read a key from the environment are not covered yet.
  • A computer taken over while an approval lasts gets the keys you released to it.
  • On the web approver, someone who knows your phone's passcode can approve.
  • No recovery yet: with one approver, losing it (or Safari clearing the web app after 7 days unused) loses the account, and secrets stored only in Custos are lost if every computer that holds them is lost.
  • On a Mac, the 1Password bridge runs in dev mode: an agent can take the 1Password access token and read your vault until you rotate it.
  • Hiding the key in responses is a safety net, not a guarantee.
  • Values you type into the custos command line on the agent's computer can be watched by the agent, even in service mode. Type important secrets on your phone (today the web approver; see the limit on its code).
  • We also serve the web approver. Until the phone apps can approve, you trust the code we serve each time it loads: changed code could get your secrets (the values you type into it, or by changing what you approve, for example adding an address) and read their names and reasons.
  • A relay that shows different histories to different devices is caught only by a manual check: after you revoke something, your phone shows 4 words; type them into a command on each computer, and if they differ that computer locks itself. In dev mode an agent on that computer could undo that lock.
  • Our relay sees the names you gave your devices, which device asked and when, whether a computer runs in dev mode or can become root, how often each key is used and by which computer, whether you approved, denied or tapped 'This wasn't me', for how long and for how many uses, and (with notifications on) which push service your phone uses.
  • Revoking a stolen phone stops its approvals, but it keeps the account secret: together with a backup of one of your computers it can read values, including secrets you add later.
  • Never give the code your phone shows for adding another phone to a terminal, chat or AI agent: whoever types it can become an approver.
Parts not built yet 2
  • Planned Stand-in keys. Planned: stand-in keys so command-line tools work without a real key on disk.
  • Planned Touch ID on your Mac. Planned: approve a single command on your Mac with your finger, for things you started yourself.
Parts that work with a limit 6
  • Works today, with limits Mac app. Shows what Custos is doing on this Mac.
  • Works today, with limits Apple, Google push. Tells your phone that something is waiting, never what.
  • Works today, with limits iPhone app. Can't approve yet: pairs today; approving with Face ID is being built.
  • Works today, with limits Android app. Can't approve yet: pairs today; approving with your fingerprint is being built.
  • Works today, with limits 1Password. Stays your vault.
  • Works today, with limits Azure Key Vault. Stays your vault.

Every limit, with its source, is on the docs system map and on the security review.

Every part as text (15)

  • Your AI agent

    Sees only names and times · Your computer

    Asks for a secret by name and gets the result of the call.

    Custos is built as if this part were hostile: nothing depends on it being honest.

    Not Custos

    Everything about this part

    Through its eyes

    • In clear

      In dev mode (today's default), it can reach Custos's keys.

      In service mode: no secret in clear.

    • Never sees

      the secret values, when Custos runs as its own user and your account can't become root. See limits

    • What it knows
      • The names of your secrets and the answers to its calls

  • The agent's plug-in

    Sees only names and times · Your computer

    Five simple tools the agent can call.

    Custos is built as if this part were hostile: nothing depends on it being honest.

    Works today

    Everything about this part

    Through its eyes

    • In clear

      In dev mode (today's default), it can reach Custos's keys.

      In service mode: no secret in clear.

  • Command line

    Can see a secret · Your computer

    For you: set up, import a.env file, check status.

    Custos is built as if this part were hostile: nothing depends on it being honest.

    Works today

    Everything about this part

    Through its eyes

    • In clear

      Can see a secret, only at the moments described.

  • Mac app

    Sees only names and times · Your computer

    Shows what Custos is doing on this Mac.

    Works today, with limits Read-only status, activity and background services on main.

    Everything about this part

    Through its eyes

    • In clear

      In dev mode (today's default), it can reach Custos's keys.

      In service mode: no secret in clear.

  • Custos on your computer

    Can see a secret · Your computer

    Holds one half of the unlock key for each secret; the other half comes from your phone only when you approve.

    Lower-security option: Dev mode: Custos runs as your own user (and five more). How you are told

    Works today

    Everything about this part

    Through its eyes

    • In clear

      Can see a secret, only at the moments described.

    • Never sees

      a stored secret without your approval

    • What it knows
      • A secret only in memory: while it stores one you add
      • While your approval lasts

  • Stand-in keys

    Can see a secret · Your computer

    Planned: stand-in keys so command-line tools work without a real key on disk.

    Planned Designed.

    Everything about this part

    Through its eyes

    Not built yet. When built, it would see:

    • In clear

      Can see a secret, only at the moments described.

  • Touch ID on your Mac

    Carries locked boxes · Your computer

    Planned: approve a single command on your Mac with your finger, for things you started yourself.

    Planned Designed.

    Everything about this part

    Through its eyes

    Not built yet. When built, it would see:

    • Sees no secret in clear.

  • Our relay

    Carries locked boxes · The internet

    Passes the question to your phone and your answer back.

    Custos is built as if this part were hostile: nothing depends on it being honest.

    Works today

    Everything about this part

    Through its eyes

    • Sees no secret in clear.

    • Never sees

      your secrets, their names, or why the agent asked. See limits

    • What it knows
      • The names you gave your devices
      • Which device asked and when
      • Whether a computer runs in dev mode or can become root
      • How often each key is used and by which computer
      • Whether you approved, denied or tapped 'This wasn't me'
      • For how long and for how many uses
      • Which push service your phone uses

  • Apple, Google push

    Carries locked boxes · The internet

    Tells your phone that something is waiting, never what.

    Custos is built as if this part were hostile: nothing depends on it being honest.

    Works today, with limits The deployed relay has Web Push, APNs (sandbox) and FCM turned on (GET /v1/relay, 2026-10-25).

    Everything about this part

    Through its eyes

    • Sees no secret in clear.

  • Approver web app

    Can see a secret · Your approver devices

    Shows which computer asks, for which key, where it will go, and the agent's stated reason.

    Lower-security option: Approving in the web app, where your phone's passcode also counts (and six more). How you are told

    Works today

    Everything about this part

    Through its eyes

    • In clear

      Can see a secret, only at the moments described.

  • iPhone app

    Carries locked boxes · Your approver devices

    Can't approve yet: pairs today; approving with Face ID is being built.

    Works today, with limits On main: pairing, an approval key under Face ID, a read-only inbox and notification code (real push delivery not yet tested).

    Everything about this part

    Through its eyes

    • Sees no secret in clear.

  • Android app

    Carries locked boxes · Your approver devices

    Can't approve yet: pairs today; approving with your fingerprint is being built.

    Works today, with limits On main: pairing, an approval key under a fingerprint, a read-only inbox and notification code (real push delivery not yet tested).

    Everything about this part

    Through its eyes

    • Sees no secret in clear.

  • GitHub, OpenAI and others

    Can see a secret · Services you already use

    Custos sends your key only to the addresses you allowed for it, in the request header the service expects (in service mode; see limits for dev mode).

    Not Custos

    Everything about this part

    Through its eyes

    • In clear

      Can see a secret, only at the moments described.

  • 1Password

    Can see a secret · Services you already use

    Stays your vault.

    Works today, with limits Tested against a stand-in op program; never run against a real 1Password account.

    Everything about this part

    Through its eyes

    • In clear

      Can see a secret, only at the moments described.

  • Azure Key Vault

    Can see a secret · Services you already use

    Stays your vault.

    Works today, with limits Tested against the Lowkey Vault emulator and a fake Entra; no live tenant in the gate.

    Everything about this part

    Through its eyes

    • In clear

      Can see a secret, only at the moments described.