orun Status API: node health and deployment state

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.

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.

Accessing the API remotely

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

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:

{"status": "ok"}

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.

curl -X POST http://localhost:9100/healthz

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.

object

required

Node-level status information.

Show node fields

string

required

The node name passed to orun start --node-name.

string

required

RFC 3339 timestamp of when the agent process started.

string

RFC 3339 timestamp of the most recent successful git sync. null if no sync has completed yet.

string

The commit SHA currently checked out from the manifest repository. null if no sync has completed yet.

string

The error message from the last failed git sync attempt. null when the last sync succeeded.

object

required

A map of deployment name to deployment status. Each key is the deployment’s metadata name from its manifest.

Show deployment status fields

string

required

Deployment name.

string

required

The container image currently running (or last attempted).

string

The Docker container ID. Omitted when no container is running.

string

required

Lifecycle state of the deployment. One of: pending, running, stopped, errored.

string

required

RFC 3339 timestamp of the last state transition.

string

Error message when state is errored. Omitted otherwise.

object

required

A map of service name to service status. Each key is the service’s metadata name from its manifest.

Show service status fields

string

required

Service name.

string

required

Name of the deployment this service routes to.

string

The domain currently configured in the Caddy ingress. Omitted when no domain is active.

boolean

required

true when the ingress route is configured and active in Caddy.

string

Error message if the service reconciler encountered a problem. Omitted otherwise.

Example request and response

curl -X POST http://localhost:9100/status

{
  "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
    }
  }
}

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

Get Started

Core Concepts

Configuration

Guides

Reference

orun Status API: node health and deployment state

Accessing the API remotely

POST /healthz

POST /status

Example request and response

​Accessing the API remotely

​POST /healthz

​POST /status

​Example request and response

Accessing the API remotely

POST /healthz

POST /status

Example request and response