> ## 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 agents — Manage Agent Leases and Secret Requests

> ironrun agents commands list, approve, deny, revoke, and fulfill strict per-command agent leases and secret requests for sensitive workflows.

Agent leases provide per-command approval for sensitive workflows. When leases are enabled, every `run_sealed` call from an agent is blocked until a human explicitly approves it — no blanket session grants. This makes leases the right choice for `staging`, `prod`, or any policy where you want an audit trail of exactly which commands were allowed and when.

## Difference from trust sessions

|                      | `ironrun trust`                    | `ironrun agents`                       |
| -------------------- | ---------------------------------- | -------------------------------------- |
| Approval granularity | One approval for the whole session | One approval per command set           |
| Agent argv           | Arbitrary                          | Bound to specific command IDs          |
| Best for             | Normal local development           | Sensitive environments, CI, production |
| Opt-in required      | No                                 | Yes — `require_agent_leases: true`     |

## Enable leases in `ironrun.yml`

```yaml theme={null}
version: "2"
require_agent_leases: true
```

With this flag set, an agent calling `run_sealed` is blocked until you approve a lease for the requested command IDs.

## Subcommands

```bash theme={null}
ironrun agents list                      # show pending requests
ironrun agents approve <request-id>      # approve a lease request
ironrun agents deny <request-id>         # deny a pending request
ironrun agents leases                    # show active leases
ironrun agents revoke <lease-id>         # revoke a lease immediately
ironrun agents fulfill <request-id>      # fulfill a secret request
```

The command also accepts `access` as an alias:

```bash theme={null}
ironrun access list
```

### `agents list`

Lists pending agent requests. Each line shows the request ID, kind (`lease` or `secret`), status, environment, session ID, and expiry. For lease requests, the requested command IDs and TTL are shown. For secret requests, the alias and key name are shown.

<ParamField query="--all" type="boolean" default="false">
  Include resolved and expired requests in the output, not just pending ones.
</ParamField>

### `agents approve`

Approves a pending lease request. ironrun creates a lease and immediately unblocks the waiting MCP call.

```bash theme={null}
ironrun agents approve req_abc123
# Approved lease lease_xyz789 for session abc123...
# Environment: dev
# Commands: test, build
# Expires: 2025-01-15T14:30:00Z
```

<ParamField query="--ttl" type="duration" default="(requested TTL)">
  Override the lease lifetime. The agent's requested TTL is used by default. Maximum is 24 hours.
</ParamField>

### `agents deny`

Denies a pending secret or lease request. The waiting MCP call is unblocked with a denial response.

```bash theme={null}
ironrun agents deny req_abc123
# Denied req_abc123.
```

### `agents leases`

Lists all agent leases sorted by expiry time. Status values are `active`, `revoked`, and `expired`.

### `agents revoke`

Immediately revokes a lease. The revocation is checked before the next command execution — a command already in flight is not interrupted.

```bash theme={null}
ironrun agents revoke lease_xyz789
# Revoked lease_xyz789. It cannot authorize another command.
```

### `agents fulfill`

Fulfills a pending secret request through a masked local prompt. The value is stored directly in the encrypted vault and is never sent through the MCP channel.

```bash theme={null}
ironrun agents fulfill req_abc123
# Masked prompt for the secret value
# Fulfilled STRIPE_SECRET_KEY for environment dev. The value was never displayed or sent through MCP.
```

## Lease lifecycle

<Steps>
  <Step title="Agent requests a lease">
    The agent calls `request_lease` with one or more command IDs from the policy, a reason, and a desired TTL.
  </Step>

  <Step title="Command is blocked">
    The `run_sealed` MCP call is blocked. The agent receives a wait response and polls for status.
  </Step>

  <Step title="You review the request">
    The request appears in `ironrun agents list` and in the TUI Inbox tab.

    ```bash theme={null}
    ironrun agents list
    # req_abc123  lease     pending  env=dev  session=abc123...  expires=2025-01-15T12:30:00Z
    #   commands=test,build  requested_ttl=1h
    #   reason=running the test suite before the PR merge
    ```
  </Step>

  <Step title="You approve">
    ```bash theme={null}
    ironrun agents approve req_abc123
    ```

    ironrun creates the lease and automatically resumes the blocked MCP call.
  </Step>

  <Step title="Lease expires or is revoked">
    The lease expires after the approved TTL. You can revoke it at any time with `ironrun agents revoke`.
  </Step>
</Steps>

## Lease pins

A lease is bound to the exact MCP server session, environment, command set, and expiry. Restarting the MCP server creates a new session and invalidates all leases associated with the old session — the agent must request new leases.

<Note>
  Leases require opt-in via `require_agent_leases: true` in `ironrun.yml`. They are off by default for compatibility. For normal local development where you trust the agent broadly, trusted sessions (`ironrun trust`) are simpler.
</Note>