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

Nine 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
Volume	`volume_mounted`, `volume_mount_denied`, `volume_committed`, `volume_ingested`, `volume_deleted`, `volume_file_write`, `volume_file_rename`, `volume_file_delete`	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 and can be read back over the API with your normal API key — no administrator involvement required.

curl "https://api.declaw.ai/accounts/$OWNER_ID/audit?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl "https://api.declaw.ai/accounts/$OWNER_ID/sandboxes/sbx-a1b2c3d4/audit" \
  -H "X-API-Key: YOUR_API_KEY"

import os, requests

owner = requests.get(
    "https://api.declaw.ai/auth/me",
    headers={"X-API-Key": os.environ["DECLAW_API_KEY"]},
).json()["owner_id"]

page = requests.get(
    f"https://api.declaw.ai/accounts/{owner}/audit",
    headers={"X-API-Key": os.environ["DECLAW_API_KEY"]},
    params={"category": "lifecycle", "limit": 100},
).json()

for e in page["entries"]:
    print(e["timestamp"], e["event"], e["sandbox_id"])
print("total:", page["pagination"]["total"])

Find your owner_id with GET /auth/me. An account can only read its own audit log — requesting another account’s returns 403.

Query parameters

Parameter	Description
`limit`	Page size. Defaults to `20`, maximum `100` — a larger value returns `400`.
`offset`	Rows to skip, for paging through `pagination.total`.
`category`	Filter to one category — any of those in What gets recorded, lower-cased, e.g. `lifecycle`.
`event`	Filter to one event name, e.g. `vm_killed`.
`sandbox_id`	Filter to a single sandbox (equivalent to the per-sandbox route).

Response shape

{
  "owner_id": "acc-fc0aae6a",
  "entries": [
    {
      "id": 13537040,
      "sandbox_id": "sbx-0fe1af65eeadb2e8c1f331ca44722ece",
      "node_id": "node-declaw-worker-4",
      "event": "vm_killed",
      "category": "lifecycle",
      "detail": null,
      "source": "orchestrator",
      "timestamp": "2026-07-30T11:51:47.865209Z"
    }
  ],
  "pagination": { "total": 8827, "limit": 20, "offset": 0, "has_more": true }
}

detail carries event-specific context and is populated for most events; it is null where an event needs no extra context. source identifies which component recorded the event — orchestrator for VM lifecycle and in-sandbox activity, sandbox-manager for control-plane API events. The per-sandbox route returns the same entries and pagination, with sandbox_id in place of owner_id.

There is no SDK helper for this yet — call the endpoint directly, as above. Remember the 7-day retention window: export anything you need to keep for longer.

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

Query parameters

Response shape

​Default: audit on

​Opt out for sensitive workloads

​Account-wide default

​AuditConfig model

​What gets recorded

​Retention

​Accessing audit data

​Query parameters

​Response shape

Default: audit on

Opt out for sensitive workloads

Account-wide default

AuditConfig model

What gets recorded

Retention

Accessing audit data

Query parameters

Response shape