Know what you’re trusting.
The local tool uses secrets on your behalf. One-time links reveal them to a recipient. Each has a different security boundary.
Local tool
Use a secret without putting its value in the conversation.
You
Enter it in the private local page.
You see the secretLocal tool
Holds the value in process memory.
Readable by the toolAgent
Reference + redacted results
No secret valueApproved API
Receives it over HTTPS for your request.
Destination receives it
The agent uses a reference. The tool returns redacted results, not the secret value.
Local fill bypasses our service. This shows the API flow; separately approved commands receive the value too.
The secrethandoff program gives secrets to AI agents. With local fill, a page served by the program on your computer receives the value into process memory, and the agent gets only its name. The value goes to APIs that you approve, never to the Secret Handoff service. The program writes no secrets to disk and sends no telemetry.
Grouped local requests collect 2–8 secrets on one page under one policy. All fields are submitted together; forgetting the group or any member erases the whole group. Grouped fill currently requires a browser on the agent's computer.
When a supported Chromium browser is available, local entry uses a separate temporary profile with extensions, sync, and password saving disabled. Requests share its window as incognito tabs. Closing the last Secret Handoff tab retires that browser after 30 seconds; ending the agent session closes it immediately. Closing the browser does not erase secrets already held by the running agent session. The default-browser opt-out does not provide this isolation.
Chat cards show request status only; you enter the value on the Secret Handoff page. Filled secrets have no automatic timer. They remain until explicitly forgotten or the tool process ends. Forgetting a secret also cancels its open request in the program, so an old fill page cannot restore it.
- The secret never enters the chat, the transcript, or the AI model's context.
- Through
http_request, the agent can call an API without ever holding the key. The program sends the secret only to the hosts, methods, and paths that you approved, and removes it from responses. - You approve each
run_with_secretcommand in the program's browser page, or in an interactive Claude Code permission prompt when you explicitly enable that mode. You can also opt into Codex's approval settings, including automatic review, allow rules, and hooks; that mode does not require a fresh human click. The command holds the secret and can send it anywhere; its network policy is not enforced. - An approved request can do anything that the key allows on the approved host.
- The program runs as your user account. Other programs that run as you can try to interfere. The page shows a request that someone else filled, and you can cancel it.
- A secret that you paste into the chat is saved by the agent client on your computer before any check runs.
Phone and remote handoffs
Encrypted delivery to the tool that requested the secret.
Your device
Check the pairing code, then encrypt locally.
You see the secretOur relay
Stores ciphertext for one pickup.
Encrypted copy onlyRequesting tool
Decrypts into memory on the agent’s machine.
Readable by the toolAgent
Reference + redacted results
No secret valueApproved API
Receives it over HTTPS when used.
Destination receives it
The agent gets a reference and redacted results. In remote mode, you confirm the handoff before use.
The relay cannot decrypt the stored copy. The phone page’s code and the machine running the tool must still be trusted.
Not yet available on the public service. Phone and remote handoffs remain disabled until the independent protocol review is complete. The following describes their design.
When you choose to fill a request on your phone, Secret Handoff only relays it. Your phone encrypts the secret with HPKE for the program that asked, so the service stores only a copy that it cannot read, and it deletes that copy after one pickup or when the request expires. Before you send anything, check that the pairing code on your phone matches the code on your computer. A link that someone sends you shows a different code.
When the agent runs on a machine without a browser, the program uses remote mode. The encrypted value is picked up into memory on that machine. Before use, you must read the fill confirmation code from your device back to the agent. A request link may appear in the transcript when the client cannot show it separately; that link does not let its reader recover the secret.
The phone page runs code that this website delivers. A changed copy of the website could read what you type there. If you do not want to trust that, run secrethandoff fill with the link in a terminal instead.
One-time sharing links
For a recipient who needs to read the secret itself.
Your browser
Encrypts before upload; the key stays in the link fragment.
You see the secretOur service
Stores ciphertext until retrieval or expiry.
Encrypted copy onlyRecipient’s browser
Opens and decrypts after an explicit retrieval.
Recipient sees the secret
Retrieval destroys the service’s encrypted copy. The recipient can still save the revealed secret, including in an agent’s context.
Encryption happens in your browser
Your device creates a random 256-bit key and encrypts the secret with AES-256-GCM before upload. The key stays in the link fragment (the part after #), which browsers do not send to web servers.
One retrieval wins
The recipient proves they possess the link key, and the database conditionally destroys the encrypted record as it returns it. Concurrent attempts cannot both succeed. Link-preview scanners never consume a secret because retrieval requires an explicit button press.
A one-time link reveals the plaintext to its recipient, whether that is a person or an agent. Deleting the encrypted copy from the service does not delete a recipient's copy. An agent that reads the revealed value can retain it in its context or transcript.
Passphrases are a true second factor
When enabled, the passphrase and link key are combined locally using PBKDF2 and HKDF. A wrong passphrase cannot retrieve or consume the ciphertext, and the passphrase is never sent to the service. After 10 wrong attempts, the service destroys the encrypted copy, so even a short passphrase cannot be guessed. The sender's receipt shows that this happened.
Limits reduce abuse
Payload, lifetime, per-address, daily, and total-capacity limits keep the public service predictable. Cloudflare Turnstile protects creation without requiring an account.