Audit log

shed records every change, sign-in, denial, read of a secret, and agent tool call in an audit log in shed.db: who did it, to what, and whether it worked. It is always on.

What is recorded

The audit log is a table in shed.db, written whether or not anything else is turned on. Each event records:

  • When. The time, to the millisecond, in UTC.
  • Who. An actor kind, and a GitHub login for people and agents.
  • What. A dotted action such as service.variables.update, the project and service it belongs to, and the ID of the thing acted on.
  • How it went. ok, failed (shed refused or could not finish it, including invalid requests), or denied (an authentication or signature check failed).
  • Detail. Names as they were at the time, such as the service, host, or mount path, plus which fields or variable keys changed.

Detail never holds a value. Saving variables records which keys were added, changed, and removed. A new start command is recorded as fields: ["startCommand"]. A new S3 secret is recorded as fields: ["secretAccessKey"]. Names stay readable after the service they belong to is deleted.

Open it in the dashboard under Server, Audit. Filter by actor (a login or a kind), action group, service, and outcome. Events load newest first, 100 at a time.

Actors

KindWho
userSomeone signed in to the dashboard, by GitHub login.
agentAn MCP client acting for a user. The login is the user's; detail names the client.
githubA push webhook with a valid signature.
systemshed itself, such as a push deployed when it retries.
dockerA container event: an exec into a container, or an OOM kill. No login.
anonymousA request that has not signed in: denials, first-run setup, and OAuth token requests.

Events don't say where a request came from: shed does not store client addresses.

Actions

ActionWhen
auth.signin, auth.signin.denied, auth.logoutDashboard sign-in. A denied sign-in is a GitHub account not in allowed_users.
setup.github, setup.token.invalidFirst-run GitHub App setup.
oauth.grant, oauth.denied, oauth.revokeAgent consent, a refused token request or bearer token, revoking a client.
webhook.signature.invalidA webhook delivery whose signature does not match.
project.create, .rename, .delete
service.create, .update, .delete, .stop, .start, .restart, service.fence.clearupdate lists the changed fields.
service.variables.update, service.variables.read, service.variables.resolved.readSaving, and viewing values in the dashboard or API.
deployment.create, .redeploy, .cancelManual deploys, and each push that deploys.
domain.create, .delete, volume.create, .delete
backup.run, .download, .restore, .delete, backup.policy.update, backup.settings.update, backup.key.readScheduled backups are not recorded; they are in the backup list.
onepassword.connect, .disconnect
notification.channel.create, .update, .delete, .test, notification.rule.updateChannels and rules. A channel's target is never recorded.
update.download, .install, update.settings.update
audit.settings.updateChanging the retention below.
telemetry.enable, .disable, .settings.update, .data.delete, telemetry.component.restartTelemetry toggled, tuned, cleared, or a component restarted.
mcp.callEvery MCP tool call, with the tool and its IDs, times, and limits, never a query, span name, or tags.
container.exec, container.oomA docker exec into a service container, with the command; a container killed for running out of memory.

container.exec is recorded for execs that nobody in shed started, such as docker exec on the server, with the command line as the daemon reports it (cut at 2 KiB). It is not recorded for the execs shed runs itself or for a container's health check. The command is stored as typed, so keep secrets out of docker exec arguments. shed follows Docker's events whether telemetry is on or off, but not while it is stopped.

A push that has to wait, for a running backup or a fenced service, is recorded once, when it deploys, not on every retry.

Repeated denials

Denials from anonymous requests are coalesced: a burst of bad webhook signatures, setup tokens, or OAuth tokens becomes one event per action per minute, whichever addresses it came from, with detail.count saying how many there were. The dashboard shows the count beside the action. Denials by signed-in users, such as declining an agent's consent, are recorded one by one.

Retention

Events older than the retention are deleted when shed starts and every hour after. The default is 365 days, and it can be set from 1 to 3650 days on the Audit page or with PUT /api/audit/settings. The setting lives in shed.db, so it is part of every shed.db backup, and so is the log itself. Changing it is recorded as audit.settings.update.

Reading it from the API and agents

the last failed or denied events about one service
curl -s 'https://shed.example.com/api/audit?service=<serviceID>&outcome=failed' \
  -H 'Cookie: shed_session=<your session token>'

GET /api/audit takes actor (a login or a kind), action (an action or its dotted prefix, so service matches service.create and service.variables.update), service (a service ID), outcome, limit (default 100, at most 500), and before. It returns {events, next}, where next is the before of the following page and null at the end. See the HTTP API.

Agents use the audit_events tool, which takes the same filters plus since, either an RFC 3339 time or a duration such as 24h. It helps an agent answer "what changed before this service broke?"