Sandboxes

Every agent turn in Diminuendo executes inside an isolated sandbox — a short-lived compute environment with its own filesystem, network namespace, and process tree. The gateway does not create or manage sandboxes directly. It delegates to Podium, which provisions the execution environment and reports lifecycle events back through the WebSocket event stream. This page explains the three-layer sandbox architecture: Podium provisions the environment, Chronicle mounts the workspace, and the gateway tracks state and enforces security policy.

Architecture

Client
  │
  ▼
Gateway (Diminuendo)
  │  Tracks sandbox state via events
  │  Enforces security profiles for automations
  │  Broadcasts lifecycle events to subscribers
  │
  ▼
Podium (Coordinator)
  │  Creates compute instances
  │  Provisions Docker / E2B containers
  │  Manages agent processes inside containers
  │  Emits sandbox lifecycle events
  │
  ▼
Sandbox (Docker / E2B microVM)
  │  Isolated filesystem, network, processes
  │  Chronicle workspace mounted at /workspace
  │  Agent tools execute within the container boundary

The gateway never SSH-es into a sandbox, never mounts filesystems, and never spawns processes inside containers. Its sole responsibility is relaying sandbox lifecycle events to clients and enforcing security policy at the protocol level. All container orchestration is Podium’s domain.

Sandbox Lifecycle

A sandbox follows a four-phase lifecycle, tracked through gateway events:

Init

When a session starts its first turn, Podium creates a compute instance and begins provisioning a sandbox. The gateway receives a sandbox.init event and broadcasts sandbox_ready (on success) or reports provisioning progress to subscribers.Gateway event: sandbox_init — includes the provider name (e.g., "e2b", "docker")

Provisioning

The sandbox is being set up — installing dependencies, configuring the environment, mounting the Chronicle workspace. Podium emits progress events that the gateway relays as sandbox_provisioning.Gateway event: sandbox_provisioning — includes phase (e.g., "creating", "configuring", "installing_deps") and an optional message

Ready

The sandbox is fully provisioned and the agent can execute tools. The gateway broadcasts sandbox_ready and updates the session metadata so clients can display sandbox status.Gateway event: sandbox_ready

Removed

The sandbox has been torn down — either because the session was deactivated, the turn completed, or a timeout fired. The gateway broadcasts sandbox_removed with a reason.Gateway event: sandbox_removed — includes reason (e.g., "session_deleted", "timeout", "manual") and an optional message

Sandbox State in the Gateway

The gateway tracks sandbox state in two places:

State Snapshot

When a client joins a session (join_session), the state_snapshot response includes a sandbox field:

{
  "type": "state_snapshot",
  "sessionId": "...",
  "session": { "..." },
  "sandbox": {
    "status": "ready",
    "provider": "e2b"
  }
}

If no sandbox exists (the session has not been activated or has been deactivated), sandbox is null.

Session Updates

Sandbox lifecycle changes are broadcast as session_updated events to the tenant topic, so all connected clients (not just those joined to the session) see the sandbox status in their session list:

// From src/session/handlers/sandbox.ts
yield* ctx.publishTenantEvent({
  type: "session_updated",
  session: {
    id: ctx.sessionId,
    sandbox: { status: "ready" },
  },
})

Sandbox Providers

Podium supports multiple sandbox providers. The gateway is provider-agnostic — it relays events regardless of which provider created the sandbox.

E2B microVMs

Cloud-hosted microVMs via the E2B platform. Each sandbox gets a dedicated VM with its own kernel, filesystem, and network stack. Used for production workloads requiring strong isolation.

Docker Containers

Local or cloud Docker containers for development and testing. Lighter-weight than microVMs, but share the host kernel. Used for local development stacks and CI environments.

The E2B_API_KEY and E2B_DOMAIN environment variables configure the E2B provider. For Docker, Podium uses the local Docker daemon.

File Access Through Sandboxes

Clients access files in the agent’s workspace through the gateway, which proxies requests to Podium’s file API:

Client Message	Gateway Action	Podium API
`list_files`	Proxy to Podium	`GET /api/v1/instances/{id}/files`
`read_file`	Proxy to Podium	`GET /api/v1/instances/{id}/files/{path}`
`file_history`	Proxy to Podium	`GET /api/v1/instances/{id}/files/{path}/history`
`file_at_iteration`	Proxy to Podium	`GET /api/v1/instances/{id}/files/{path}/at/{n}`

All file operations require an active Podium instance (and therefore an active sandbox) for the session. If the session is inactive, the gateway rejects file access with an error. Chronicle provides the versioned filesystem layer inside the sandbox. Every file modification creates a new iteration, enabling clients to browse version history and read files at any historical point. See Chronicle Integration for details.

Sandbox Security for Automations

Interactive sessions run with the user watching — the human can intervene if the agent does something unexpected. Automation runs are unattended, which requires stricter sandboxing.

Security Profiles

Each automation carries a security profile that Podium enforces at the container level:

Profile	Network	Filesystem	Use Case
`restricted` (default)	No outbound except LLM provider	Read-write within `/workspace` only	Code analysis, test running, file review
`networked`	Outbound via egress proxy with domain allowlist	Read-write within `/workspace` only	GitHub API access, external service monitoring
`custom`	Admin-configured policy	Admin-configured policy	Special integrations (requires `automation:admin` permission)

The gateway validates security profiles at automation creation time and passes them to Podium when starting a run:

// AutomationEngine passes security context to Podium
yield* sessionRuntime.startTurn({
  sessionId: runSessionId,
  tenantId: identity.tenantId,
  agentType: automation.agentType,
  text: automation.prompt,
  metadata: {
    automationId: automation.id,
    runId: run.id,
    securityProfile: automation.security?.profile ?? "restricted",
    isUnattended: true,
  }
})

Filesystem Isolation

The container filesystem is restricted to exactly what the agent needs:

Container filesystem:
  /workspace/          ← Chronicle workspace for this tenant+session
  /tmp/                ← Ephemeral scratch space (size-limited)
  /                    ← Read-only base image (agent runtime, tools)

NOT visible:
  /data/tenants/       ← Gateway SQLite databases
  /data/sessions/      ← Other sessions' databases
  Other tenants' workspaces

The gateway’s control-plane databases (registry.db, session.db) are never mounted into any sandbox. They reside on the gateway’s local filesystem, physically separate from the container mount namespace.

Permission Requests in Sandboxes

When an agent inside a sandbox encounters a sensitive operation, it emits question_requested or permission_requested events. The gateway:

Broadcasts the event to all session subscribers
For automation runs: transitions the run to waiting status and creates an inbox item
Waits for the user to respond via answer_question

Automation runs never auto-approve sensitive operations — all permission requests require human confirmation, even for restricted profile runs. If a run remains in waiting status beyond a configurable timeout, it is canceled.

Sandbox Lifecycle During Shutdown

When the gateway shuts down gracefully:

The server_shutdown event is broadcast to all session topics
Active Podium connections are closed
Podium instances are stopped via DELETE /api/v1/instances/{id}
Sandboxes are torn down by Podium as a consequence of instance deletion

On ungraceful shutdown (process crash, OOM kill), the stale session recovery mechanism runs on startup and resets all non-idle sessions to inactive. The Podium instances associated with those sessions will have already been reclaimed by Podium’s own timeout mechanism.

Configuration

Variable	Default	Description
`E2B_API_KEY`	`""`	API key for E2B sandbox provider
`E2B_DOMAIN`	`e2b-dev.igent.dev`	E2B domain for sandbox URLs
`PODIUM_URL`	`http://localhost:5082`	Podium coordinator URL (manages sandbox lifecycle)

The gateway does not provision sandboxes itself. All sandbox configuration flows through Podium. The E2B_API_KEY is passed to Podium (via instance environment variables or Podium’s own configuration) — the gateway stores it for configuration validation and health reporting, not for direct E2B API calls.

What the Gateway Does vs Does Not Do

Responsibility	Gateway (Diminuendo)	Podium
Create sandbox	No	Yes
Provision dependencies	No	Yes
Mount Chronicle workspace	No	Yes
Enforce network policy	No (defines policy)	Yes (enforces at container level)
Track sandbox state	Yes (via events)	Yes (source of truth)
Broadcast lifecycle events	Yes	No (emits raw events)
File access proxy	Yes	Yes (serves file API)
Stop sandbox on session delete	Yes (calls Podium API)	Yes (executes container teardown)
Recover after crash	Yes (resets stale sessions)	Yes (reclaims timed-out instances)

Getting Started

Architecture

Wire Protocol

Client SDKs

Frontend Clients

Platform Integration

Operations

Sandboxes

Sandboxes

Architecture

Sandbox Lifecycle

Sandbox State in the Gateway

State Snapshot

Session Updates

Sandbox Providers

E2B microVMs

Docker Containers

File Access Through Sandboxes

Sandbox Security for Automations

Security Profiles

Filesystem Isolation

Permission Requests in Sandboxes

Sandbox Lifecycle During Shutdown

Configuration

What the Gateway Does vs Does Not Do

Getting Started

Architecture

Wire Protocol

Client SDKs

Frontend Clients

Platform Integration

Operations

​Sandboxes

​Architecture

​Sandbox Lifecycle

​Sandbox State in the Gateway

​State Snapshot

​Session Updates

​Sandbox Providers

E2B microVMs

Docker Containers

​File Access Through Sandboxes

​Sandbox Security for Automations

​Security Profiles

​Filesystem Isolation

​Permission Requests in Sandboxes

​Sandbox Lifecycle During Shutdown

​Configuration

​What the Gateway Does vs Does Not Do

Sandboxes

Architecture

Sandbox Lifecycle

Sandbox State in the Gateway

State Snapshot

Session Updates

Sandbox Providers

File Access Through Sandboxes

Sandbox Security for Automations

Security Profiles

Filesystem Isolation

Permission Requests in Sandboxes

Sandbox Lifecycle During Shutdown

Configuration

What the Gateway Does vs Does Not Do