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

# Automate ironrun via the Local Unix Socket HTTP API

> ironrun exposes a local Unix socket HTTP API for scripted status checks, sealed execution, and access management from shell scripts and CI tools.

`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

```bash theme={null}
ironrun serve
```

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

## Endpoints

| Method | Path         | Description                                           |
| ------ | ------------ | ----------------------------------------------------- |
| `GET`  | `/v1/status` | Project and environment metadata                      |
| `POST` | `/v1/run`    | Sealed execution with `{"command_id", "environment"}` |

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.

```bash theme={null}
# Check project and environment status
curl --unix-socket .ironrun/ironrun.sock http://localhost/v1/status
```

```bash theme={null}
# Run a sealed command
curl --unix-socket .ironrun/ironrun.sock \
  -H 'Content-Type: application/json' \
  -d '{"command_id":"test","environment":"dev"}' \
  http://localhost/v1/run
```

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

<CardGroup cols={2}>
  <Card title="CI automation" icon="gear">
    Trigger sealed commands from CI scripts without exposing secrets to the CI environment's process list or job logs.
  </Card>

  <Card title="Shell script orchestration" icon="terminal">
    Wrap ironrun commands in shell scripts that check status, run commands conditionally, and act on exit codes — all without reading secret values.
  </Card>

  <Card title="Status dashboards" icon="chart-bar">
    Poll `/v1/status` from monitoring scripts or internal dashboards to display environment state without revealing credentials.
  </Card>

  <Card title="Access management" icon="key">
    Approve, revoke, or inspect agent leases and trusted sessions programmatically from scripts using the access and trust endpoints.
  </Card>
</CardGroup>

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

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