Agent logs

stashbase agent run writes a local, metadata-only JSONL audit log by default. Startup prints the audit session ID, policy fingerprint, and local log path. Use stashbase agent logs list to inspect recent Agent Proxy decisions without opening those files directly. stashbase agent logs remains an alias for list.

What logs contain

Each event records the profile, policy fingerprint, Agent Proxy action, destination host, binding name, binding source, response status, and duration. binding_source identifies whether the binding came from a Stashbase secret or a Personal Credential. Completed HTTP events also record relayed request and response byte counts; these are not Content-Length values and are absent when traffic is denied before forwarding or is tunneled. Logs never include secret values, placeholders, headers, bodies, URLs, or command arguments.

The session_started event includes the selected profile source plus a modification time and content hash for its profile file. This connects a session to the reviewed profile revision without storing the policy itself in every event.

Common actions include injected, host_denied, unknown_placeholder, tls_trust_failed, upstream_timeout, upstream_connection_failed, and upstream_request_failed.

Resolve a denied request

Start by finding the denied host, then make the smallest appropriate policy change:

1. Run stashbase agent logs list --action host_denied --since 1h.
2. Run stashbase agent explain --verbose with the host, method, and path to see the policy decision.
3. Add a narrow credential rule when the destination must receive the credential; otherwise, add the host to egress_hosts for ordinary traffic without credential injection.
4. Run stashbase agent validate and stashbase agent policy test before starting the agent again.

Keep deny_hosts for destinations that must remain blocked, including the Stashbase API host when the profile permits broad egress.

View recent events

stashbase agent logs list
stashbase agent logs --session 5fd2...
stashbase agent logs --profile coding --action injected --host api.github.com
stashbase agent logs --id evt_...
stashbase agent logs list --action host_denied --since 1h
stashbase agent logs list --follow
stashbase agent logs summary --profile coding --since 7d
stashbase agent logs summary --profile coding --by host

Use --json for a one-time JSON array. With --follow --json, each event is emitted as one JSON line. summary reports request, injection, forward, and denial totals with uploaded and downloaded bytes; use --by host, --by action, or --by secret to group the results. --by secret groups by binding names only, never secret values.

Each local event has an opaque evt_-prefixed ID. Safe proxy errors include the ID when available, so stashbase agent logs --id <event-id> can locate the underlying local audit record.

Retention and privacy

Logs older than 30 days are removed automatically and local storage is capped at 1,000 session files. Disable persistence for one run with --audit-log false:

stashbase agent run --profile coding --audit-log false -- codex