> ## 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 trust — Manage Trusted Agent Workspace Sessions

> ironrun trust commands grant, pause, extend, and revoke two-hour workspace sessions so AI agents can run commands without per-command approval.

Trusted workspace sessions are the fast path for normal local development. Approve once, and the agent can run any command in the current project and environment for the session duration — without requiring a separate approval for each one. Secrets are still injected below agent visibility and redacted from all output; the agent never holds a raw credential value.

## How sessions work

<Steps>
  <Step title="Agent requests access">
    The agent calls the `request_workspace_access` MCP tool with a reason, or simply attempts `run_sealed` with an `argv` array.
  </Step>

  <Step title="Request appears in your Inbox">
    The request shows up in the global Inbox — visible in the TUI (bare `ironrun`) or via `ironrun agents list`.
  </Step>

  <Step title="You grant the session">
    Review the request and grant it with a single command:

    ```bash theme={null}
    ironrun trust grant <request-id>
    ```
  </Step>

  <Step title="Agent works normally">
    For the duration of the session, the agent can call `run_sealed` with any `argv`. Each command still has secrets injected and output redacted — the agent sees `[REDACTED]` wherever a secret value would appear.
  </Step>

  <Step title="Session expires or you revoke it">
    The session expires automatically after the configured TTL (default: 2 hours). You can revoke it at any time with `ironrun trust revoke <trust-id>`.
  </Step>
</Steps>

## Subcommands

```bash theme={null}
ironrun trust list                        # show active trusted sessions
ironrun trust grant <request-id>          # approve a pending request
ironrun trust pause <trust-id>            # temporarily suspend without revoking
ironrun trust extend <trust-id> --ttl 2h  # resume or extend expiry from now
ironrun trust revoke <trust-id>           # revoke immediately
```

### `trust list`

Lists all trusted workspace sessions with their status, environment, session ID, network mode, and expiry time. Status values are `active`, `paused`, `revoked`, and `expired`.

### `trust grant`

Approves a pending workspace access request and creates a trusted session. The `--ttl` flag sets the session lifetime; the default is the `DefaultWorkspaceTTL` (2 hours) and the maximum is 24 hours.

```bash theme={null}
ironrun trust grant req_abc123
# Trusted session abc123... for environment dev until 2025-01-15T14:30:00Z.
# Normal network access is enabled; revoke anytime with `ironrun trust revoke <id>`.
```

<ParamField query="--ttl" type="duration" default="2h">
  Override the trusted session lifetime from now. Maximum is 24 hours. Accepts Go duration strings such as `1h`, `2h`, `8h`.
</ParamField>

### `trust pause`

Suspends a trusted session without revoking it. The agent's next `run_sealed` call will be blocked until you extend the session with a fresh expiry.

```bash theme={null}
ironrun trust pause trust_abc123
# Paused trust_abc123. Use `ironrun trust extend trust_abc123 --ttl 2h` to resume.
```

### `trust extend`

Resumes a paused session or pushes the expiry forward from the current time.

```bash theme={null}
ironrun trust extend trust_abc123 --ttl 2h
```

<ParamField query="--ttl" type="duration" default="2h">
  New lifetime measured from now. Maximum is 24 hours.
</ParamField>

### `trust revoke`

Immediately revokes a trusted session. The session cannot authorize any further commands after revocation.

```bash theme={null}
ironrun trust revoke trust_abc123
# Revoked trust_abc123. It cannot authorize another workspace command.
```

## Session pins

A trusted session is bound to the exact MCP server session, project, and environment. If the MCP server restarts, a new session is created and the old grant does not transfer — you need to approve a fresh request.

## Scope

The default scope of a trusted session is the current `dev` environment. Granting access to `dev` does not allow the agent to run commands against `staging` or `prod`. Those environments require a separate explicit grant.

<Warning>
  Trusted sessions allow the agent to supply arbitrary `argv` to `run_sealed`. A trusted agent could exfiltrate secrets through network requests or file writes, even though ironrun redacts values from command output. ironrun protects agent context, logs, and routine output — it is not an OS sandbox for a process you choose to trust. Use short TTLs and revoke sessions when the work is complete.
</Warning>

<Tip>
  Run `ironrun trust list` before starting any sensitive work to see which sessions are currently active. Revoke any session you didn't intend to leave open.
</Tip>