Audit Logging

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.

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.

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):

Per-sandbox AuditConfig(enabled=...) on the SecurityPolicy — overrides everything.
Account-wide toggle — applied when the sandbox policy omits audit.enabled.
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.

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

Default: audit on

Opt out for sensitive workloads

Account-wide default

AuditConfig model

What gets recorded

Retention

Accessing audit data

​Default: audit on

​Opt out for sensitive workloads

​Account-wide default

​AuditConfig model

​What gets recorded

​Retention

​Accessing audit data

Default: audit on

Opt out for sensitive workloads

Account-wide default

AuditConfig model

What gets recorded

Retention

Accessing audit data