> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> System diagram, component roles, and monorepo structure for Declaw's secure sandbox platform.

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

```mermaid theme={null}
graph TB
    subgraph clientLayer [Client Layer]
        SDK["SDKs\nPython | TypeScript"]
        SDKParts["Sandbox | AsyncSandbox | Template | SecurityPolicy"]
    end

    subgraph controlPlane [Control Plane - Kubernetes]
        SandboxManager["Sandbox Manager\nGin REST :8080 | Auth | Sandbox CRUD"]
        NodeCollector["Node Collector\nWorker state :8090"]
        Guardrails["Guardrails Service\nFastAPI :8000 | ML scanners"]
        Postgres["PostgreSQL\nState | Policies | Templates"]
        Redis["Redis\nCache | Routing | Sessions"]
    end

    subgraph orchestrationLayer [Orchestration - Bare Metal]
        Orchestrator["Orchestrator\nVM Lifecycle :9090 | Network Setup"]
        TemplateCache["Template Cache\nNBD Storage | Snapshots | GCS/S3"]
    end

    subgraph firecrackerVM [sandbox MicroVM per Sandbox]
        Envd["envd\nHTTP/REST :49983\nFilesystem | Process | PTY"]
        SecProxy["Security Proxy\nIn-orchestrator interceptor\nPer-sandbox CA | iptables NAT"]
        Workload["Agent Workload\nUser Code | AI Agent"]
    end

    SDK --> SDKParts
    SDKParts -->|"HTTPS"| SandboxManager
    SandboxManager --> Postgres
    SandboxManager --> Redis
    SandboxManager -->|"HTTP"| Orchestrator
    SandboxManager --> NodeCollector
    Orchestrator --> TemplateCache
    Orchestrator -->|"spawn VMs"| Envd
    Workload -->|"all outbound traffic"| SecProxy
    SecProxy -->|"scan"| Guardrails
    SecProxy -->|"cleaned traffic"| Internet["Internet"]
    Internet -->|"response"| SecProxy
    SecProxy --> Workload
```

## 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()`:

```mermaid theme={null}
sequenceDiagram
    participant SDK as Python SDK
    participant API as Sandbox Manager
    participant DB as PostgreSQL
    participant Orch as Orchestrator
    participant VM as sandbox VM
    participant Envd as envd

    SDK->>API: POST /sandboxes {template, envs, network, security}
    API->>DB: Store sandbox state + security policy
    API->>Orch: HTTP CreateSandbox(config)
    Orch->>VM: Boot sandbox VM (rootfs + kernel)
    VM->>Envd: Start envd on :49983
    VM->>VM: Start security-proxy, generate CA, set iptables
    Orch-->>API: SandboxReady {sandbox_id, envd_token}
    API-->>SDK: 201 {sandbox_id, access_tokens}

    SDK->>Envd: POST /sandboxes/{id}/commands (via Sandbox Manager → envd)
    Envd->>Envd: exec process, capture stdout/stderr
    Envd-->>SDK: CommandResult {stdout, stderr, exit_code}
```

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Architecture sub-pages

| Page                                           | What it covers                                                 |
| ---------------------------------------------- | -------------------------------------------------------------- |
| [sandbox](/architecture/firecracker)           | MicroVM internals: rootfs, TAP networking, boot process, envd  |
| [Security Proxy](/architecture/security-proxy) | TLS, certificate generation, scanning pipeline                 |
| [Packet Flow](/architecture/packet-flow)       | Network packet diagrams: iptables, TCP proxy, HTTP/HTTPS flows |