Read the audit log

Merge the operator-side and on-host JSONL logs to see every state change that yoink made, also for deploys whose containers no longer exist.

Read as MarkdownEdit on GitHub

yoink history reads container labels, so a removed container has no history line. The audit log is the durable record. It has two files and one merged read path:

SideFileEvents
Operator$XDG_STATE_HOME/yoink/audit/events.jsonl (default ~/.local/state/yoink/audit/)Fleet-wide: RunStarted, RunFinished, and validation or build failures that never reach a host.
Host/var/lib/yoink/audit/events.jsonl on each managed hostPer-host, for example LockAcquired, LockReleased, ContainerStarted, ContainerCreated, and DeployFailed.

Each line has an event_id (UUIDv7), and the merged view uses it to remove duplicates. The origin field ("operator" or "host") shows which file the line came from.

Read everything from the last week

yoink audit log

The default window is 7d and the default limit is 100 rows. The newest row comes first.

ts                        origin    host                    deploy_id                 event                         details
2026-05-01T15:42:01.317Z  operator  —                       0190f0c7-c5b1-7c98-…      RunFinished                   up ok
2026-05-01T15:42:01.299Z  host      cax11.example.com       0190f0c7-c5b1-7c98-…      LockReleased
2026-05-01T15:41:58.612Z  host      cax11.example.com       0190f0c7-c5b1-7c98-…      ContainerCreated              docs docs-3fdc075b tag=sha-3fdc075
2026-05-01T15:41:42.005Z  host      cax11.example.com       0190f0c7-c5b1-7c98-…      LockAcquired
2026-05-01T15:41:42.005Z  operator  —                       0190f0c7-c5b1-7c98-…      RunStarted                    up services=[docs]

Each run gets one deploy_id (UUIDv7). A lexicographic sort puts the runs in the sequence of their start times.

Filter by side

yoink audit log --origin operator   # only the local file
yoink audit log --origin host       # only the on-host SSH fetches

To see only the events that one host recorded, use --origin host together with --host <ADDR>.

Reconstruct one run

Pass the deploy_id of the run, or a unique prefix of it:

yoink audit log --deploy-id 0190f0c7-c5b1-7c98-aa92-1d77b8e91f10
# or, since the prefix is unique:
yoink audit run 0190f0c7

The command shows every event of that run, across every host, with the newest event first.

Filter by host, service, or event type

Use --host, --service, --event, and --since. You can repeat --event.

yoink audit log --host docs.example.com
yoink audit log --service api --event ContainerCreated --event DeployFailed
yoink audit log --since 30m --format json | jq 'select(.event == "DeployFailed")'

--format json writes raw JSONL, one event per line, for jq, vector, or a different tool.

Find failed deploys

yoink audit log --event DeployFailed --since 30d

A DeployFailed event has the last 30 log lines of the failed container in log_tail. yoink removes the containers of a failed attempt, so the audit log is the only place that keeps these lines.

Retention and rotation

Each active file, on the operator side and on each host, rotates at 5 MiB. yoink renames the file to events-<UTC-timestamp>.jsonl and starts a new file. If --since is more than 24 hours, yoink audit log also reads the rotated files.

yoink enforces no retention. To remove the rotated files on the hosts that are older than a retention window, run yoink audit gc:

yoink audit gc --keep 90d           # default retention
yoink audit gc --keep 30d --dry-run # preview before deleting
yoink audit gc --keep 30d --host docs.example.com

yoink audit gc removes rotated files only on the hosts, and it never changes an active file. Rotated files on the operator side stay until you remove them manually. If you have a strict retention requirement, schedule yoink audit gc from cron or from a deploy hook.

In the TUI

Run yoink tui and press a (or 7) to open the Audit pane. To open the pane directly, run yoink tui --mode audit. The pane shows the same merged view. Use these keys in the pane:

KeyAction
↑↓ / j kSelect a row.
EnterOpen or close a detail panel below the table. The panel shows the full event_id, the deploy_id, the actor and git SHA, and the log_tail of a failed deploy.
/Start a substring filter across host, event name, summary, deploy_id, and actor. Enter applies the filter. Esc cancels the edit.
rFetch the log again (parallel SSH per host plus one local read for the operator log).
EscThe first press clears the active filter. The second press returns to the Dashboard.

See also

Type a flag, a config field, or a task.