Audit events and JSONL collectors

The controller stores audit records in the events table of its existing SQLite database. Events in the terminal and browser reads this journal directly. Opening it does not wait for a complete host/project inventory. Pages contain 100 records; the server caps requests at 500 and seeks by durable event ID.

What is recorded

Records cover service/resource/secret grants and revocations, MCP approval and rules delivery, account registration/configuration, server sign-in/sign-out, session and workspace lifecycle changes, cleanup, and other controller operations. They are metadata about these actions, not a transcript of every shell command, network request, or database query performed by an agent.

Access history separately records managed HTTP/CONNECT and MCP attempts with policy/outcome metadata. Its bounded pages, address summaries, JSONL export and live feed reuse Events retention and streaming settings. It is not a full packet, shell or SQL transcript either.

Each record has id, createdAt, kind, subjectId, detail, context, ownerUserId, and actorUserId. Context includes the known project, workspace and session identifiers. A request initiated by an authenticated user records that user as actor. Host/background events and older records can have a null actor. The original journal is retained across controller restart; it is not an immutable or signed compliance archive.

Audit producers omit secret values and command/prompt payloads. The journal also redacts credential-shaped text and URL credentials when storing and reading records. Export uses the same sanitized view; it never exports raw SQLite rows, provider transcripts, .agent.env, or managed-secret files.

In server-user mode, each user sees and exports only their own records. Another user with an administrator role does not receive global operator events. The recovery operator can inspect all records. Historic records without provable ownership remain operator-only instead of being assigned to another user.

Settings and retention

Settings separates Hotkeys, History cleanup, and Log streaming. Hotkeys are personal preferences; the latter two are server administrator settings shared by native TUI and web.

Retention

Open Settings → History cleanup → Audit events to enable automatic cleanup, set retention days, the maximum retained record count and the check interval. Defaults are 90 days, 100,000 records and a 60-minute interval. A pass removes at most 5,000 oldest eligible events. Further passes continue reducing an oversized journal. Save and clean now explicitly runs a pass even if automation is off. Export important history before lowering retention. Deleted records cannot be replayed by a collector; retain them long enough for collectors to catch up. Freed SQLite pages are reused; cleanup does not run a blocking VACUUM or promise that the database file immediately shrinks.

History cleanup → Command results controls a separate archive of completed infrastructure commands. Defaults are 30 days, 512 MiB and a five-minute interval. Closed JSONL files are removed oldest first; current-day journals, recent writes, active legacy migration files and files referenced by retained sessions or pending operations remain protected. Its size limit is soft when protected files exceed the budget. Storage also has a shortcut to this policy.

These policies never delete conversation transcripts, project files, task artifacts, Docker volumes or containers. Those have their own cleanup workflow. The controller runs retention maintenance without an open TUI or browser. Settings and the last cleanup report survive controller restart.

Administrator APIs (also discoverable by operator MCP controller_operations):

Export from the interface

Open Events and select Export JSONL, or press e with content focused. The export includes all retained events visible to the current user, rather than only the page displayed.

The UI shows the request in flight and elapsed time: reading the journal, preparing a download, reading export batches, or saving the local file. Exchange similarly distinguishes reading project folders, reading entries/sizes/sync status, and copying/finalizing a file. Repository and service-access dialogs show their actual API steps. A timer never invents a new backend stage.

HTTP integration

GET /v1/events remains a compatible recent-record array. GET /v1/events/page returns {events,nextCursor,latestCursor}. Use before with descending pages or after with ascending pages; nextCursor is null at the end. IDs, rather than timestamps, distinguish events created in the same millisecond. Optional projectId and workspaceId filters require ownership.

GET /v1/events/export streams application/x-ndjson in ascending ID order. It pins a through watermark when the request starts, so new records cannot extend the download indefinitely. Optional after, before, and through bound the export. For example, use your controller origin and a private credential file:

curl --fail --silent --show-error \
  --header "Authorization: Bearer $(cat /run/secrets/devctrl_audit_token)" \
  'https://controller.example/v1/events/export?after=1000' \
  --output devctrl-events.jsonl

Only the existing controller/server-user authentication is supported; there is no additional unrestricted collector credential. Keep operator credentials private. A server-user credential exports that user's scope. Browser private keys are exchanged by the web gateway for single-use, path-bound transfer links; controller credentials are not placed in URLs.

Live WebSocket integration

Open Settings → Log streaming to enable/disable the feed and configure its poll interval (100–10,000 ms), heartbeat (5–120 seconds) and batch size (10–500 events). Defaults remain 500 ms, 15 seconds and 100 events. Changes apply to active streams on their next poll; disabling closes them and refuses new collectors. Recording and JSONL exports remain available when streaming is off. The screen shows active collector count and endpoint paths. Use the actual controller origin and an authenticated handshake; secret values are not shown. These WebSocket settings configure the inbound feed. Your external collector connects to devctrl and forwards records to the log system you choose.

Controller stdout and local Unix sockets

Open Settings → Log streaming → Local outputs (l) to select controller stdout or a private Unix socket on the server. Each channel is disabled by default. Select audit, network and MCP categories independently, choose the visible owner/project scope and save. The controller runs these outputs without an open TUI, browser or desktop client.

Stdout means the controller process output, including its service/container logs. It is restricted to the infrastructure recovery operator because those logs are shared. Other application users can configure only an own-scope Unix socket. The screen shows its generated server path, connection state, counters and last error. Read it with a local collector running as the controller OS user, for example socat - UNIX-CONNECT:<displayed-socket-path> | jq .. The private directory is mode 0700, the socket 0600; client-supplied paths and incoming commands are not supported. Long controller data paths use a short private managed temporary namespace to fit Unix socket limits.

Output is redacted NDJSON metadata: audit.event and access.attempt. It includes neither audit free text nor prompts, request bodies, MCP arguments, credentials or terminal output. A socket accepts one reader. Slow readers are disconnected and can reconnect; backpressured stdout pauses its own worker without stopping journal recording. Pending records stay in the retained journals rather than an unbounded memory queue.

Enabling a channel or changing its scope/categories starts at the live cursor. Reconnects and controller restarts resume saved cursors within retained history; records can repeat and collectors should deduplicate by event ID or access cursor. Socket writes confirm local transport acceptance, not durable storage in a collector. Disabling a user closes its output. Existing authenticated WebSocket collection and JSONL export remain available independently.

GET/PUT /v1/events/stream/local exposes these settings and health. Operator MCP discovers the route through controller_operations and uses controller_request; ordinary session MCP does not acquire controller-wide log access.

A collector can connect to wss://controller.example/v1/events/stream?after=1000 with the normal Authorization: Bearer … handshake. With no after, the stream catches up from the beginning. It then reads new durable records approximately every 500 ms. The controller can continue recording and streaming without a TUI or browser client.

Frames are JSON:

{"type":"audit.ready","cursor":1000,"latestCursor":1050}
{"type":"audit.event","event":{"id":1001,"createdAt":"…","kind":"resource.granted","subjectId":"…","detail":"…","context":{},"ownerUserId":"…","actorUserId":null}}
{"type":"audit.cursor","cursor":1050}
{"type":"audit.heartbeat","cursor":1050}

Forward only the event object as a JSONL record into your existing log collector or its stdin/file input. For example, Node with the already installed ws package can read the stream:

import {readFileSync} from 'node:fs';
import {WebSocket} from 'ws';
const socket = new WebSocket(process.env.DEVCTRL_AUDIT_URL, {
  headers: {Authorization: 'Bearer ' + readFileSync(process.env.DEVCTRL_AUDIT_TOKEN_FILE, 'utf8').trim()},
});
socket.on('message', data => {
  const message = JSON.parse(String(data));
  if (message.type === 'audit.event') process.stdout.write(JSON.stringify(message.event) + '\n');
});
socket.on('error', () => {process.exitCode = 1;});

For a production collector, persist the last event ID after your destination has durably accepted that event, reconnect with after=<saved-id>, and dedupe by (controller identity, event.id). Do not treat receiving audit.cursor as proof your log system persisted the batch. This is resumable, at-least-once collection; devctrl does not promise exactly-once external delivery or manage your external collector/sink.

Catch-up is bounded to the configured batch size and does not copy the whole journal into a subscriber queue. A slow subscriber over 1 MiB of socket buffering is closed with 1013; resume from the last saved ID. Limits are four streams per user and 32 per controller. A stream accepts no input commands. User logout, credential expiry or user disable closes it; a reconnect must authenticate again. Heartbeats are sent every 15 seconds by default. Browser consumers use the same web-gateway authenticated socket relay as other live endpoints, with an origin-bound ticket.