Skip to main content
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):
  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

FieldTypeDefaultDescription
enabledboolTrueWhether 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:
CategoryEventsAlways recorded?
Lifecyclevm_created, vm_killed, vm_paused, vm_resumed, plus _failed counterpartsYes
Adminwallet_adjustment, admin_tier_change, admin_kill, admin_refundYes
Networkegress_allowed, egress_blocked — destination domain, IP/port, and the rule that firedNo
Commandcommand_exec, command_stream — command string (truncated to 512 chars), working directory, userNo
Filesystemfile_read, file_write, file_remove, file_rename, file_list, file_mkdir, file_batch, file_read_raw, file_write_rawNo
Snapshotvm_snapshot_started, vm_snapshot_completed, vm_snapshot_failed, vm_restore_started, vm_restored, vm_restore_failedNo
PTYpty_create, pty_stream, pty_stdin, pty_resize, pty_killNo
Securityinjection_detected, injection_blocked, toxicity_detected, toxicity_blocked, pii_redaction, and other guardrails scan eventsNo
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.