> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Logging

> What Declaw records for lifecycle and security events, how long it's kept, and how to opt out.

Declaw records a fixed set of lifecycle and security events for every
sandbox. Events are emitted by the orchestrator and node collector and
persisted in the platform database. Request and response **bodies are
not logged** — guardrails (PII, injection defense, etc.) emit their own
metrics; see their respective pages for those.

## Default: audit on

Audit logging is on by default. No configuration is required.

```python theme={null}
from declaw import Sandbox

sbx = Sandbox.create(template="base")
# Lifecycle + egress decisions are recorded automatically.
```

## Opt out for sensitive workloads

Pass `AuditConfig(enabled=False)` (or the shorthand `audit=False`) to
suppress **command**, **filesystem**, **snapshot**, **network**, **pty**,
and **security** events for a sandbox at the source — nothing ships to
the collector for those categories, nothing is persisted.

Lifecycle and admin events are always recorded regardless of this
toggle. They contain no user-generated content and are required for
billing and platform operations.

```python theme={null}
from declaw import Sandbox, SecurityPolicy, AuditConfig

sbx = Sandbox.create(
    template="base",
    security=SecurityPolicy(audit=AuditConfig(enabled=False)),
)
```

## Account-wide default

Flip audit logging off for your entire account from the console at
**Settings → API Keys → Audit logging**. The toggle sets the default
that's injected into every new sandbox whose `SecurityPolicy` doesn't
set `audit.enabled` explicitly.

Precedence (most specific wins):

1. Per-sandbox `AuditConfig(enabled=...)` on the `SecurityPolicy` — overrides everything.
2. Account-wide toggle — applied when the sandbox policy omits `audit.enabled`.
3. Platform default — on.

The toggle only affects **future** sandboxes. Sandboxes already running
keep the audit state they booted with.

## AuditConfig model

| Field     | Type   | Default | Description                                   |
| --------- | ------ | ------- | --------------------------------------------- |
| `enabled` | `bool` | `True`  | Whether events for this sandbox are recorded. |

## What gets recorded

Eight categories of events, each with a sandbox id, node id, timestamp,
event name, category, and a JSON `detail` payload:

| Category   | Events                                                                                                                                | Always recorded? |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | :--------------: |
| Lifecycle  | `vm_created`, `vm_killed`, `vm_paused`, `vm_resumed`, plus `_failed` counterparts                                                     |        Yes       |
| Admin      | `wallet_adjustment`, `admin_tier_change`, `admin_kill`, `admin_refund`                                                                |        Yes       |
| Network    | `egress_allowed`, `egress_blocked` — destination domain, IP/port, and the rule that fired                                             |        No        |
| Command    | `command_exec`, `command_stream` — command string (truncated to 512 chars), working directory, user                                   |        No        |
| Filesystem | `file_read`, `file_write`, `file_remove`, `file_rename`, `file_list`, `file_mkdir`, `file_batch`, `file_read_raw`, `file_write_raw`   |        No        |
| Snapshot   | `vm_snapshot_started`, `vm_snapshot_completed`, `vm_snapshot_failed`, `vm_restore_started`, `vm_restored`, `vm_restore_failed`        |        No        |
| PTY        | `pty_create`, `pty_stream`, `pty_stdin`, `pty_resize`, `pty_kill`                                                                     |        No        |
| Security   | `injection_detected`, `injection_blocked`, `toxicity_detected`, `toxicity_blocked`, `pii_redaction`, and other guardrails scan events |        No        |

**Always recorded** categories (lifecycle, admin) are logged regardless
of the audit toggle. They contain no user-generated content and are
required for billing and platform operations.

**Gated** categories (network, command, filesystem, snapshot, pty,
security) respect the per-sandbox and account-wide audit toggle. When
audit is off, these events are not shipped to the collector.

HTTP request/response bodies, PII detection counts, and injection scores
are **not** written to the audit log.

## Retention

Audit events are kept for **7 days** platform-wide, then deleted by a
nightly cleanup job in the node collector. Retention is not configurable
per sandbox today — it's a single, predictable window for all tenants.

## Accessing audit data

Audit events are stored platform-side. There is no SDK call to retrieve
them today — query the platform database directly if you have access,
or contact your Declaw administrator.