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

# Workspace Access MCP Tools: Request and Check Trust

> request_workspace_access and workspace_status let agents request a trusted session and query project and environment metadata. No secret values returned.

Before an agent can run arbitrary argv with `run_sealed`, it needs a trusted workspace session. A workspace trust grant is project-scoped, environment-scoped, and pinned to the current MCP server process — restarting the server creates a new session, and an old grant does not carry over. The `request_workspace_access` tool initiates a trust request that the human approves via the CLI or the Inbox TUI. The `workspace_status` tool lets an agent inspect safe session metadata without triggering any side effects.

## `request_workspace_access`

Submits a trust request for this MCP session. The request is visible in the global ironrun Inbox immediately.

### Parameters

<ParamField body="reason" type="string" required>
  A brief description of what you intend to do. This is shown to the human when they review the request. Be specific: "running the test suite against the dev database" is more useful than "need access".
</ParamField>

<ParamField body="argv" type="array of strings">
  An optional first command for human context. This helps the human understand what the agent is about to run. The command is **not executed** by this request — it is display-only.
</ParamField>

### Response

The tool returns the request ID and its initial status (`pending`), along with instructions for the human:

```
Trusted workspace request req_abc123 is pending for environment "dev".
A human can approve it in ironrun's Agent Access screen or with
`ironrun trust grant req_abc123`. The request expires in 2h.
```

### Human approval

The human can approve the request in three ways:

<Steps>
  <Step title="CLI">
    ```bash theme={null}
    ironrun trust grant req_abc123
    ```
  </Step>

  <Step title="Inbox TUI">
    Run `ironrun` with no arguments to open the global workspace. Requests appear on the Inbox tab. Press Enter to review and approve.
  </Step>

  <Step title="Trust management">
    ```bash theme={null}
    ironrun trust list           # see all pending and active grants
    ironrun trust pause <id>     # temporarily suspend a grant
    ironrun trust extend <id> --ttl 2h
    ironrun trust revoke <id>    # end access immediately
    ```
  </Step>
</Steps>

Once approved, the grant is active for two hours by default. The agent can call `run_sealed` with any argv for the granted project and environment during that window.

<Note>
  You do not have to call `request_workspace_access` before `run_sealed`. If you call `run_sealed` with an `argv` and no trust grant exists, ironrun automatically creates the access request and blocks until the human approves it.
</Note>

***

## `workspace_status`

Returns value-blind metadata about the current project, active environment, and session trust state. Call this to discover what environment is active and to confirm whether a trust grant is already in place before attempting `run_sealed`.

### Parameters

This tool takes no parameters.

### Response

```
Project: /Users/alice/projects/myapp
Environment: dev
Configured entries: DATABASE_URL, STRIPE_SECRET_KEY, RESEND_API_KEY
Session: trusted until 2025-06-15T16:00:00-07:00 (normal network)
```

If the session is not yet trusted:

```
Project: /Users/alice/projects/myapp
Environment: dev
Configured entries: DATABASE_URL, STRIPE_SECRET_KEY
Session: not trusted
```

<Note>
  `workspace_status` never returns secret values. The "Configured entries" list contains only the names of the configured secrets — not their values.
</Note>

***

## Typical agent workflow

<Steps>
  <Step title="Check current status">
    Call `workspace_status` to discover the active environment and confirm whether a trust grant is already active.
  </Step>

  <Step title="Request access if needed">
    If the session shows "not trusted", call `request_workspace_access` with a clear reason.

    ```
    request_workspace_access({
      "reason": "running the test suite to diagnose the failing CI build",
      "argv": ["go", "test", "./..."]
    })
    ```
  </Step>

  <Step title="Wait for human approval">
    The human approves with `ironrun trust grant <request-id>` or through the Inbox TUI. The agent waits — no further action needed.
  </Step>

  <Step title="Confirm trust and proceed">
    Call `workspace_status` again to confirm the session is now trusted, then proceed with `run_sealed`.
  </Step>
</Steps>

***

## Scope and security notes

Workspace trust grants have a narrow scope by design:

* They are pinned to a single MCP server process. Restarting `ironrun mcp` creates a new session; the old grant cannot be transferred.
* They are scoped to the active project and environment. A grant for `dev` does not authorize commands in `staging` or `prod` — those require separate explicit grants.
* Normal development network access is enabled within a trusted session. ironrun protects agent context, logs, and routine output from leaking secret values. It is not an OS-level process sandbox.
* You can revoke a grant at any time with `ironrun trust revoke <id>`.