Architecture Overview

Declaw is a monorepo of Go services and Python/TypeScript SDKs that together provide secure, isolated code execution for AI agents. The system has three conceptual layers: a client layer (SDKs), a control plane (sandbox-manager, node-collector, guardrails) deployed via Helm, and the execution layer (sandbox microVMs managed by an orchestrator on bare metal).

System diagram

Component breakdown

Control plane (Helm-deployed)

Component	Path	Role
Sandbox Manager	`infra/sandbox-manager/`	REST API (Gin framework) on port 8080, authentication, sandbox + template CRUD, tier enforcement
Node Collector	`infra/node-collector/`	Worker state repository on port 8090, tracks live sandboxes across orchestrator nodes
Guardrails	`infra/guardrails/`	FastAPI ML scanner service on port 8000 — PII, prompt injection, toxicity, code security, invisible text
Shared	`infra/shared/`	Common Go library — models, auth, blobstore, telemetry

Orchestration (bare metal)

Component	Path	Role
Orchestrator	`infra/orchestrator/`	sandbox VM lifecycle on port 9090, network namespace management, per-sandbox security proxy, template caching
envd	`infra/orchestrator/envd/`	In-VM daemon, HTTP/REST (+ SSE) on port 49983, filesystem API, process management, PTY support — bundled into the rootfs image

SDKs

Module	Path	Role
Python — sync	`python-sdk/declaw/sandbox_sync/`	Synchronous sandbox API
Python — async	`python-sdk/declaw/sandbox_async/`	Async mirror of all sync APIs
Python — security	`python-sdk/declaw/security/`	SecurityPolicy, PIIConfig, NetworkPolicy, etc.
TypeScript	`ts-sdk/src/`	Promise-based sandbox API with full TS types

Request flow

End-to-end flow for Sandbox.create() followed by sandbox.commands.run():

Monorepo structure

declaw/
├── python-sdk/                 # Python SDK (sync + async)
│   └── declaw/
│       ├── sandbox_sync/       # Synchronous implementation
│       ├── sandbox_async/      # Async mirror
│       ├── security/           # SecurityPolicy, PII, injection, etc.
│       └── template/           # Template management
├── ts-sdk/                     # TypeScript SDK (@declaw/sdk)
├── cookbook/                   # 49 runnable examples + integration tests
├── templates/                  # sandbox rootfs definitions (base, python, node, …)
├── spec/                       # OpenAPI + gRPC/proto definitions
├── docs/                       # Architecture & design docs
├── client_docs/                # Mintlify documentation site
└── infra/                      # All deployable services
    ├── shared/                 # Go shared library (models, auth, blobstore, telemetry)
    ├── sandbox-manager/        # REST API (Helm-deployed, port 8080)
    ├── node-collector/         # Worker state repo (Helm-deployed, port 8090)
    ├── orchestrator/           # sandbox VM manager (bare metal, port 9090)
    │   └── envd/               # In-VM daemon — baked into rootfs
    ├── guardrails/             # ML security scanner (Helm-deployed, port 8000)
    ├── mock-guardrails/        # Regex-based guardrails drop-in
    ├── postgres/               # PostgreSQL (Helm-deployed)
    ├── redis/                  # Redis cache (Helm-deployed)
    └── service-discovery/      # Consul configs (bare metal)

Key design decisions

sandbox for isolation (not Docker)

Docker containers share the host kernel. A container escape exploit gives an attacker access to the host. sandbox microVMs have a hardware isolation boundary — each VM has its own kernel, memory space, and I/O devices. A compromised sandbox cannot escape to the host or to other sandboxes.

Per-sandbox network namespaces

Each sandbox gets its own Linux network namespace with a dedicated veth pair and TAP device. Sandboxes cannot see each other’s network traffic, cannot reach each other’s IPs, and cannot intercept host-level network interfaces.

Per-sandbox security proxy (host-side, outside the guest)

The security proxy runs host-side in each sandbox’s own network namespace, not inside the guest VM. Because it sits outside the guest on the only egress path, the workload can’t see, bypass, or tamper with it — all outbound traffic is forced through it. The per-sandbox CA certificate is generated fresh for each sandbox and injected into the VM trust store at boot.

OverlayFS for rootfs isolation

The base rootfs image is read-only and shared across all sandboxes. Each sandbox gets a writable overlay layer (ext4 image) on top. This makes sandbox creation fast (no full copy) and guarantees filesystem isolation. Destroying a sandbox deletes only the overlay layer.

Fail-fast on proxy errors

If the security proxy fails to start or configure iptables, the sandbox creation fails with an error. There is no “log and continue” path — a sandbox without a functioning security proxy is considered unsafe and never reaches the running state.

Architecture sub-pages

Page	What it covers
sandbox	MicroVM internals: rootfs, TAP networking, boot process, envd
Security Proxy	TLS, certificate generation, scanning pipeline
Packet Flow	Network packet diagrams: iptables, TCP proxy, HTTP/HTTPS flows

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

Architecture Overview

System diagram

Component breakdown

Control plane (Helm-deployed)

Orchestration (bare metal)

SDKs

Request flow

Monorepo structure

Key design decisions

Architecture sub-pages

​System diagram

​Component breakdown

​Control plane (Helm-deployed)

​Orchestration (bare metal)

​SDKs

​Request flow

​Monorepo structure

​Key design decisions

​Architecture sub-pages

System diagram

Component breakdown

Control plane (Helm-deployed)

Orchestration (bare metal)

SDKs

Request flow

Monorepo structure

Key design decisions

Architecture sub-pages