> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ironrun share — Encrypt Secrets for Safe Chat Transmission

> ironrun share creates short-lived ir1. ciphertexts so you can pass a secret value through chat without it appearing in plaintext in the agent transcript.

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="You create a capsule">
    ```bash theme={null}
    ironrun share create req_abc123
    # Masked prompt — the value is never echoed
    # Output: ir1.eyJhbGci...
    ```

    ironrun reads the secret through a masked prompt, encrypts it, and prints the ciphertext.
  </Step>

  <Step title="You paste the ciphertext into chat">
    Paste only the `ir1.` ciphertext. The plaintext value never enters the conversation.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Capsule expires">
    If the capsule is not claimed within 10 minutes, it becomes unusable automatically.
  </Step>
</Steps>

## Usage

```bash theme={null}
ironrun share create <request-id>
```

The `share` command also accepts `capsule` as an alias.

### Example

```bash theme={null}
ironrun share create req_abc123...
# Enter secret value:
# ir1.eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2R0NNIn0...
```

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

## Flags

### `share create`

<ParamField query="--ttl" type="duration" default="10m">
  Override the capsule lifetime. The maximum is 10 minutes. Accepts Go duration strings such as `5m` or `10m`.
</ParamField>

## Capsule properties

| Property   | Value                                                      |
| ---------- | ---------------------------------------------------------- |
| Bound to   | The specific pending request ID                            |
| Bound to   | The current MCP session                                    |
| Bound to   | The current project                                        |
| Expiry     | 10 minutes (configurable with `--ttl`, maximum 10 minutes) |
| Single-use | Yes — unusable after the request is fulfilled              |

## 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:

```bash theme={null}
ironrun agents fulfill req_abc123
```

This is the simpler option when you are at the terminal and have no need to copy anything into a chat window.

<Warning>
  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.
</Warning>