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

# Monitor containers and view logs in orun

> How to view orun agent logs via journald, query the built-in status API for deployment health, and set up lightweight monitoring tools for containers.

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:

```bash theme={null}
# 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 |

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

  ```bash theme={null}
  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.
</Note>

```bash theme={null}
# 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:

```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",
      "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:

```yaml theme={null}
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](https://beszel.dev)** — host and container metrics with a built-in dashboard
* **[Dozzle](https://dozzle.dev/)** — 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:

```bash theme={null}
# Example: ship journald logs with Vector
journalctl -u orun -f -o json | vector --config /etc/vector/vector.toml
```

Compatible collectors include [Vector](https://vector.dev/) and [Elastic Beats](https://www.elastic.co/beats/). Configure them to read from `journald` (source: `journald` unit filter `orun`) and forward to your preferred backend (Elasticsearch, Loki, Splunk, etc.).

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

<CardGroup cols={2}>
  <Card title="Deploy your first app" icon="rocket" href="/guides/deploy-your-first-app">
    Learn how Deployment manifests work and how orun reconciles them.
  </Card>

  <Card title="Enable HTTPS ingress" icon="lock" href="/guides/ssl-and-ingress">
    Expose monitoring dashboards on a domain with automatic SSL.
  </Card>
</CardGroup>