Skip to main content
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

​
reason
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”.
​
argv
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.

​
Response

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

​
Human approval

The human can approve the request in three ways:
1

CLI

2

Inbox TUI

Run ironrun with no arguments to open the global workspace. Requests appear on the Inbox tab. Press Enter to review and approve.
3

Trust management

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

​
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

If the session is not yet trusted:
workspace_status never returns secret values. The “Configured entries” list contains only the names of the configured secrets — not their values.

​
Typical agent workflow

1

Check current status

Call workspace_status to discover the active environment and confirm whether a trust grant is already active.
2

Request access if needed

If the session shows “not trusted”, call request_workspace_access with a clear reason.
3

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

Confirm trust and proceed

Call workspace_status again to confirm the session is now trusted, then proceed with run_sealed.

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