Skip to main content
ironrun serve starts an owner-only Unix socket API at .ironrun/ironrun.sock, letting shell scripts and external tooling interact with ironrun programmatically. Because the API binds to a Unix socket rather than a network port, it is accessible only to processes running as the same user on the same machine — no firewall rules or authentication tokens required.

​
Starting the server

The server runs in the foreground. Leave it running in a separate terminal or manage it with your process supervisor of choice.

​
Endpoints

The API also exposes endpoints for access requests, lease inspection, revocation, and denial — the same operations available through ironrun access and ironrun trust in the CLI.

​
curl examples

Use --unix-socket to send requests over the socket. The hostname in the URL is ignored; use http://localhost as a placeholder.
The /v1/run response includes the exit code, duration in milliseconds, and redacted stdout/stderr — the same output run_sealed returns to the MCP agent.

​
Use cases

CI automation

Trigger sealed commands from CI scripts without exposing secrets to the CI environment’s process list or job logs.

Shell script orchestration

Wrap ironrun commands in shell scripts that check status, run commands conditionally, and act on exit codes — all without reading secret values.

Status dashboards

Poll /v1/status from monitoring scripts or internal dashboards to display environment state without revealing credentials.

Access management

Approve, revoke, or inspect agent leases and trusted sessions programmatically from scripts using the access and trust endpoints.

​
Security properties

  • Owner-only socket — the Unix socket is created with permissions that allow only the owning user to connect. No other user on the machine can reach the API.
  • No plaintext secret endpoints — no API endpoint accepts or returns plaintext secret values. Secrets are resolved and injected by ironrun internally; they never transit the socket.
  • Strict JSON parsing — the API refuses requests containing unknown JSON fields, reducing the risk of unintended behavior from malformed or probing requests.
The API is strictly local. It binds to a Unix socket at .ironrun/ironrun.sock, not to a TCP port. It is not accessible over a network connection, even from localhost over TCP. Scripts running on remote machines cannot reach it.