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):
GET/PUT /v1/events/policy,POST /v1/events/cleanupGET/PUT /v1/command-results/policy,POST /v1/command-results/cleanupGET/PUT /v1/events/stream/settings
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.
- Browser: starts an authenticated attachment download. Transfer progress is in the browser download manager; devctrl does not accumulate the journal in RAM.
- Native TUI: writes batches into the mounted console directory,
.devctl/ipc/audit-exports/devctrl-events-<timestamp>.jsonl, with mode0600. The path is printed when the file has been synced. Partial exports are removed if a request fails or the screen is closed.
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.