Logs

Log retrieval is part of the WebSocket protocol, not a REST endpoint.

Use the get_logs command on /ws.

Command request

Envelope:

{
  "type": "command",
  "id": "cmd-123",
  "name": "get_logs",
  "payload": {
    "service": "api",
    "after_seq": 120,
    "limit": 200
  }
}

payload fields:

• service (string, optional): filter by service name
• after_seq (integer, optional): only return entries with seq > after_seq (forward pagination / replay)
• before_seq (integer, optional): only return entries with seq < before_seq (backward pagination / “load older”). Must be > 0. Mutually exclusive with after_seq
• limit (integer, optional): explicit max entries (> 0)

Command response (result.data)

{
  "entries": [
    {
      "seq": 121,
      "service": "api",
      "phase": "running",
      "stream": "stdout",
      "message": "ready",
      "timestamp": "2026-04-18T10:30:00Z"
    }
  ],
  "truncated": false,
  "effective_limit": 200
}

Core response fields:

• entries: ordered log entries
• truncated: whether older entries were dropped to fit the limit
• effective_limit: actual limit applied by the server

Limit resolution

Priority order:

1. explicit limit in the command payload
2. scope-specific server policy
3. global server policy
4. logs.bufferSize default (5000 unless overridden)

Scope-specific policy details:

• all-services request (no service): logView.all.maxEntries then logView.maxEntries
• service request (service set): services.<name>.logView.maxEntries then logView.maxEntries

Clients should trust effective_limit from each response as the source of truth.

Streaming vs reliable continuity

Live log events are broadcast best-effort and can be dropped under pressure.

For reliable continuity:

1. track the highest seen seq
2. call get_logs with after_seq
3. merge by seq

This is the canonical recovery path after reconnects or event loss.

Disk projection when logs.dir is set

If server config sets logs.dir, runtime projects logs to JSONL files:

• all.jsonl (all services)
• <service>.jsonl (per service)

Disk projection is best-effort; runtime memory and live protocol stream remain the authoritative session behavior.

Backward pagination with before_seq

The server keeps a bounded per-service in-memory ring buffer (logs.bufferSize, default 5000). For backward pagination (scroll-up to load older history), call get_logs with before_seq set to the lowest seq you currently hold. The server returns entries with seq < before_seq, capped by effective_limit.

When the requested range predates the in-memory ring head and logs.dir is configured, the server transparently reads the missing entries from the JSONL projection on disk — callers do not need to know whether the response came from RAM or disk. Without logs.dir, backward pagination is limited to whatever remains in the in-memory ring.