Audit Logging

What You’ll Learn

What Declaw’s audit log actually captures (lifecycle + security events, not request/response bodies)
How to opt a sandbox out of audit logging with AuditConfig(enabled=False)
The retention window and why it is platform-wide

Prerequisites

Declaw instance running and DECLAW_API_KEY / DECLAW_DOMAIN set

pip install declaw python-dotenv

Code Walkthrough

This example is available in Python. TypeScript support coming soon.

1. The default: audit on

Declaw records a fixed set of lifecycle and security events for every sandbox by default. You do not have to enable anything.

from declaw import Sandbox

sbx = Sandbox.create(template="base")
# Lifecycle + egress decisions for this sandbox are recorded
# to the platform's audit log automatically.

2. Opt out of audit logging

If a sandbox is handling sensitive workloads and you’d rather have no record at all, pass AuditConfig(enabled=False) on the policy:

from declaw import Sandbox, SecurityPolicy, AuditConfig

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

The audit field also accepts a plain boolean as a shorthand:

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

When enabled=False, the orchestrator drops gated events (network, command, filesystem, snapshot, pty, security) for that sandbox at the source — nothing is shipped to the collector for those categories. Only lifecycle and admin events are still recorded.

`AuditConfig` field	Default	Description
`enabled`	`True`	Whether events for this sandbox are recorded. Set to `False` to opt out.

3. What the audit log captures

The audit log records a fixed set of events. These are emitted by the orchestrator and node collector, not by the HTTP proxy:

Lifecycle (always recorded) — vm_created, vm_killed, vm_paused, vm_resumed, plus their _failed counterparts.
Snapshot (gated) — vm_snapshot_started, vm_snapshot_completed, vm_snapshot_failed, vm_restore_started, vm_restored, vm_restore_failed.
Network (gated) — egress_allowed and egress_blocked decisions from the per-sandbox firewall (domain, destination IP/port, rule that fired).

Each event carries the sandbox id, node id, timestamp, event name, category, and a JSON detail payload scoped to the event. Request and response bodies are not written to the audit log. PII redaction and prompt-injection scanning emit their own metrics; see the PII and injection-defense cookbook pages for how to read those.

4. Retention

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

5. Cleanup

sbx.kill()

Expected Output

============================================================
Declaw Audit Logging Example
============================================================

--- Creating Sandbox with Audit Opt-Out ---
Sandbox created: sbx_abc123

Security policy applied:
  audit.enabled: False

Audit events for this sandbox are suppressed at the orchestrator.

--- Cleaning Up ---
Sandbox killed.

============================================================
Done!
============================================================

Transformation Rules OpenAI

Getting Started

Built-in Templates

Commands

PTY

OpenAI Agents

Filesystem

Volumes

Network Policies

PII Protection

Security Features

LLM Providers

Framework Integrations

Agent-in-Sandbox

Real-World Patterns

Security Demos

What You’ll Learn

Prerequisites

Code Walkthrough

1. The default: audit on

2. Opt out of audit logging

3. What the audit log captures

4. Retention

5. Cleanup

Expected Output

​What You’ll Learn

​Prerequisites

​Code Walkthrough

​1. The default: audit on

​2. Opt out of audit logging

​3. What the audit log captures

​4. Retention

​5. Cleanup

​Expected Output

What You’ll Learn

Prerequisites

Code Walkthrough

1. The default: audit on

2. Opt out of audit logging

3. What the audit log captures

4. Retention

5. Cleanup

Expected Output