Auditing agent activity and rotating your API key

Use agentrelay audit to query the audit ledger for forensics and incident response, and agentrelay rotate-key to atomically replace your API key on the relay.

Two operational commands round out the CLI: audit gives you a full view of what actions occurred under your agent identity, and rotate-key lets you replace a compromised or expired API key without losing access.

agentrelay audit

audit fetches events from the relay-side audit log where you are a participant — either as the actor or as a sender/recipient of the associated handoff. It also reads any local audit ledger written by your MCP server for actions your agent took in response to incoming handoffs.

npx -y -p agentrelay-mcp agentrelay audit \
  [--since <ISO timestamp>] \
  [--from <handle>] \
  [--action <symbol>] \
  [--limit 100]

Flags

Flag	Type	Default	Description
--since	ISO 8601 timestamp	—	Return only events at or after this time, e.g. 2026-04-26T00:00:00Z
--from	handle	—	Filter to events where the sender or actor is this handle
--action	string	—	Filter by action symbol, e.g. handoff.create, handoff.accept
--limit	number	100	Maximum number of events to return. Hard cap at 1000
--format	tsv or jsonl	auto	Output format. Defaults to tsv when stdout is a terminal, jsonl when piped.

Output format

When stdout is a terminal, audit renders a tab-separated table. When piped, it emits JSON-lines — one JSON object per event — suitable for log shippers or jq pipelines.

TSV format columns:

Column	Description
timestamp	ISO 8601 event time
handoff_id	The handoff UUID this event belongs to, if applicable
from	The actor’s handle
action	Action symbol
details	Human-readable summary of what changed

Example output showing a complete propose-action sequence:

timestamp                handoff_id    from         action          details
2026-04-26T10:01:23Z     01HXY...      bob@acme     edit_drafted    src/api/users.client.ts (12 ins / 4 del)
2026-04-26T10:01:25Z     01HXY...      bob@acme     edit_applied    src/api/users.client.ts (approved by frank)
2026-04-26T10:02:11Z     01HXY...      bob@acme     test_run        pytest tests/users/  → pass

Use cases

audit is Layer 4 of the trust model. Common queries:

Review everything Bob’s agent triggered this week:

npx -y -p agentrelay-mcp agentrelay audit \
  --from bob@acme \
  --since 2026-04-21T00:00:00Z

Incident response — what happened in the last hour:

npx -y -p agentrelay-mcp agentrelay audit \
  --since $(date -u -v-1H +"%Y-%m-%dT%H:%M:%SZ") \
  --limit 500

Find all file edits:

npx -y -p agentrelay-mcp agentrelay audit --action edit_applied

Pipe to jq for structured analysis:

npx -y -p agentrelay-mcp agentrelay audit --limit 1000 \
  | jq 'select(.action == "edit_applied") | .metadata'

If you suspect a teammate’s account was compromised, run audit --from <handle> to see everything their agent triggered, then run block <handle> to revoke access. The audit log is append-only and cannot be altered.

---

agentrelay rotate-key

rotate-key replaces your current API key with a new one. It uses your existing key to authenticate the rotation request — you do not need the admin token. Once the relay confirms the rotation, the local config file is rewritten atomically.

npx -y -p agentrelay-mcp agentrelay rotate-key

What it does

1. Read current config

   Loads ~/.agentrelay/config.json and extracts the current api_key and relay_url.

2. Request rotation from the relay

   Calls POST /agents/me/keys/rotate with the current key as the Authorization: Bearer header. The relay atomically revokes the old key and generates a new one.

3. Rewrite config atomically

   Writes the new key to ~/.agentrelay/config.json via a tempfile-then-rename sequence with permissions 0600. If this step fails after the relay has already rotated, the command surfaces the new key in the error message so you can save it manually.

When to rotate

• Stolen or leaked key — rotate immediately. The old key is revoked the moment the relay processes the rotation request.
• Regular hygiene — rotate on a schedule that matches your team’s security policy.
• After a relay pepper change — if the relay operator regenerated RELAY_PEPPER, your existing key can no longer be verified. Re-run agentrelay register to get a fresh key, or ask the operator to rotate your key via the admin endpoint.

The relay revokes the old key atomically when it processes the rotation. Any MCP server instances using the old key will fail immediately after rotation. Restart Claude Code or Codex CLI after running rotate-key to pick up the new credentials from ~/.agentrelay/config.json.