> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# orun Status API: node health and deployment state

> Reference for the orun HTTP status API on port 9100, including POST /status for full deployment reports and POST /healthz for liveness checks.

Each orun node exposes a lightweight HTTP API on port 9100 (configurable via `--status-port`) that lets you inspect node health and the current state of all deployments and services. The server binds to `localhost` only — to query it from a remote machine, open an SSH tunnel first.

<Info>
  The status API is read-only and makes no changes to containers or configuration. It reads exclusively from the in-memory state store maintained by the agent.
</Info>

## Accessing the API remotely

Because the API listens on `localhost`, use an SSH tunnel to reach it from outside the node:

```bash theme={null}
ssh -L 9100:localhost:9100 root@<host>
```

Then query the API locally as if you were on the node.

***

## POST /healthz

Returns a simple liveness response. Use this endpoint to confirm the orun agent process is running and able to accept requests.

**Request:** no body required.

**Response:**

```json theme={null}
{"status": "ok"}
```

<ResponseField name="status" type="string" required>
  Always `"ok"` when the agent is alive. If the agent is not running, the connection will be refused rather than returning an error body.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:9100/healthz
  ```
</CodeGroup>

***

## POST /status

Returns the full `NodeReport` — a consistent, point-in-time snapshot of the node, all tracked deployments, and all active ingress routes.

**Request:** no body required.

**Response:** a `NodeReport` object.

<ResponseField name="node" type="object" required>
  Node-level status information.

  <Expandable title="node fields">
    <ResponseField name="name" type="string" required>
      The node name passed to `orun start --node-name`.
    </ResponseField>

    <ResponseField name="started_at" type="string" required>
      RFC 3339 timestamp of when the agent process started.
    </ResponseField>

    <ResponseField name="last_sync_time" type="string">
      RFC 3339 timestamp of the most recent successful git sync. `null` if no sync has completed yet.
    </ResponseField>

    <ResponseField name="git_head" type="string">
      The commit SHA currently checked out from the manifest repository. `null` if no sync has completed yet.
    </ResponseField>

    <ResponseField name="sync_error" type="string">
      The error message from the last failed git sync attempt. `null` when the last sync succeeded.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="deployments" type="object" required>
  A map of deployment name to deployment status. Each key is the deployment's metadata name from its manifest.

  <Expandable title="deployment status fields">
    <ResponseField name="name" type="string" required>
      Deployment name.
    </ResponseField>

    <ResponseField name="image" type="string" required>
      The container image currently running (or last attempted).
    </ResponseField>

    <ResponseField name="container_id" type="string">
      The Docker container ID. Omitted when no container is running.
    </ResponseField>

    <ResponseField name="state" type="string" required>
      Lifecycle state of the deployment. One of: `pending`, `running`, `stopped`, `errored`.
    </ResponseField>

    <ResponseField name="changed_at" type="string" required>
      RFC 3339 timestamp of the last state transition.
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message when `state` is `errored`. Omitted otherwise.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="services" type="object" required>
  A map of service name to service status. Each key is the service's metadata name from its manifest.

  <Expandable title="service status fields">
    <ResponseField name="name" type="string" required>
      Service name.
    </ResponseField>

    <ResponseField name="deployment" type="string" required>
      Name of the deployment this service routes to.
    </ResponseField>

    <ResponseField name="domain" type="string">
      The domain currently configured in the Caddy ingress. Omitted when no domain is active.
    </ResponseField>

    <ResponseField name="route_active" type="boolean" required>
      `true` when the ingress route is configured and active in Caddy.
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message if the service reconciler encountered a problem. Omitted otherwise.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example request and response

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:9100/status
  ```
</CodeGroup>

```json theme={null}
{
  "node": {
    "name": "web-01",
    "started_at": "2024-11-01T10:00:00Z",
    "last_sync_time": "2024-11-01T10:00:05Z",
    "git_head": "a1b2c3d4e5f6...",
    "sync_error": null
  },
  "deployments": {
    "hello-world": {
      "name": "hello-world",
      "image": "traefik/whoami",
      "container_id": "4a7f9b2e1c3d",
      "state": "running",
      "changed_at": "2024-11-01T10:00:06Z"
    }
  },
  "services": {
    "hello-world": {
      "name": "hello-world",
      "deployment": "hello-world",
      "domain": "hello-world.example.com",
      "route_active": true
    }
  }
}
```

<Warning>
  orun is pre-release software. The structure of the `NodeReport` response may change in future versions without a deprecation period.
</Warning>