Skip to main content
When a workflow requires delivering a secret value to an agent through chat — for example, to fulfill a pending request_secret — capsules let you encrypt the value before it ever enters the conversation transcript. You type the value into a masked terminal prompt, get back a short ciphertext that starts with ir1., and paste only that ciphertext into chat.

​
The problem capsules solve

A plaintext secret pasted directly into chat is in the model’s context window, may appear in the AI provider’s logs, and is written verbatim to local conversation history files — for example, Claude Code’s ~/.claude/projects/<hash>/*.jsonl files. Once the value is there, it cannot be retroactively removed. Capsules keep the plaintext out of that path entirely.

​
How capsules work

1

Agent requests a secret

The agent calls the request_secret MCP tool with a declared alias and a reason. It has no plaintext value field — only a reference.
2

You create a capsule

ironrun reads the secret through a masked prompt, encrypts it, and prints the ciphertext.
3

You paste the ciphertext into chat

Paste only the ir1. ciphertext. The plaintext value never enters the conversation.
4

Agent claims the capsule

The agent passes the ciphertext to the claim_capsule MCP tool. ironrun decrypts the value locally, stores it in the encrypted vault, and marks the capsule as consumed. The agent does not receive the plaintext.
5

Capsule expires

If the capsule is not claimed within 10 minutes, it becomes unusable automatically.

​
Usage

The share command also accepts capsule as an alias.

​
Example

Paste the ir1. line into chat. That is the only string your agent and the AI provider ever see.

​
Flags

​
share create

​
--ttl
duration
default:"10m"
Override the capsule lifetime. The maximum is 10 minutes. Accepts Go duration strings such as 5m or 10m.

​
Capsule properties

​
Alternative: fulfill directly

If you don’t need to route the value through chat at all, use the direct fulfillment path instead. It skips the capsule entirely:
This is the simpler option when you are at the terminal and have no need to copy anything into a chat window.
A plaintext secret that has already been pasted into chat cannot be retroactively removed from model-provider logs or local history files. If you accidentally paste a live credential in plaintext, treat it as compromised and rotate it immediately.