Monitor containers and view logs in orun

orun emits structured JSON logs through systemd/journald and exposes a lightweight HTTP status API on every node. Together these two surfaces give you visibility into both the orun agent itself and the containers it manages. For richer dashboards and log aggregation you can deploy dedicated tools as orun Deployments alongside your applications.

Accessing orun agent logs

Because orun runs as a systemd service, all agent output goes to journald. SSH into the node and use journalctl to read it:

# Follow live agent output
journalctl -u orun -f

# Show the last 200 lines
journalctl -u orun -n 200

# Show logs since a specific time
journalctl -u orun --since "2026-04-22 00:00:00"

Each log line is a JSON object (key-value pairs emitted by Go’s slog package), making it straightforward to pipe into jq or ship to a log aggregator.

Using the status API

The orun agent starts an HTTP server on localhost:9100 (port configurable via --status-port in orun start). It exposes two endpoints:

Endpoint	Method	Description
`/healthz`	POST	Simple liveness check — returns `{"status":"ok"}`
`/status`	POST	Full `NodeReport` JSON with every deployment’s current state

The status API binds to localhost only. To query it from your local machine, use an SSH tunnel:

ssh -L 9100:localhost:9100 root@<node-ip>

Then query http://localhost:9100/status locally. Avoid exposing port 9100 directly to the internet without an authentication layer.

# Check that the orun agent is alive
curl -X POST http://localhost:9100/healthz

# Get a full deployment status report
curl -X POST http://localhost:9100/status

A /status response looks like:

{
  "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",
      "state": "running",
      "changed_at": "2024-11-01T10:00:06Z"
    }
  },
  "services": {}
}

Health probes

For each Deployment that defines health.readiness.http or health.liveness.http, orun polls those HTTP endpoints on a recurring basis. Probe results feed directly into the /status report, so you can tell at a glance whether a container is ready to serve traffic or requires attention. Define health probes in your Deployment manifest:

spec:
  health:
    readiness:
      http: localhost:80/health
    liveness:
      http: localhost:80/health

Recommended monitoring tools

For container-level metrics and log browsing, deploy one of these lightweight tools as an orun Deployment on the same node:

Beszel — host and container metrics with a built-in dashboard
Dozzle — real-time container log viewer with a browser UI

Both run as Docker containers and require no external dependencies, making them a natural fit as orun Deployments.

Advanced: centralized log shipping

For multi-node setups or compliance requirements, deploy a log collector on each node and forward logs to a central destination:

# Example: ship journald logs with Vector
journalctl -u orun -f -o json | vector --config /etc/vector/vector.toml

Compatible collectors include Vector and Elastic Beats. Configure them to read from journald (source: journald unit filter orun) and forward to your preferred backend (Elasticsearch, Loki, Splunk, etc.).

OpenTelemetry (OTel) metrics and deployment traces are on the orun roadmap. Once available, they will provide structured observability without requiring a separate log pipeline.

Deploy your first app

Learn how Deployment manifests work and how orun reconciles them.

Enable HTTPS ingress

Expose monitoring dashboards on a domain with automatic SSL.

Get Started

Core Concepts

Configuration

Guides

Reference

Monitor containers and view logs in orun

Accessing orun agent logs

Using the status API

Health probes

Recommended monitoring tools

Advanced: centralized log shipping

Deploy your first app

Enable HTTPS ingress

​Accessing orun agent logs

​Using the status API

​Health probes

​Recommended monitoring tools

​Advanced: centralized log shipping

Deploy your first app

Enable HTTPS ingress

Accessing orun agent logs

Using the status API

Health probes

Recommended monitoring tools

Advanced: centralized log shipping