Execution Sandbox Environments

Relevant source files

The following files were used as context for generating this wiki page:

• design/sandbox.md
• src/sandbox/supervisor.integration.test.ts
• src/agent/coding/types.ts
• src/test/daytona-sandbox-fake.test.ts
• changelog.d/2026-04-17-design-drafted-autonomous-coding-container.md
• CLAUDE.md

Execution Sandbox Environments provide isolated, secure, and resource-constrained runtimes for executing autonomous coding tasks and third-party skills within Cogmo. The system supports multiple backends, primarily leveraging containerization to ensure that code execution does not compromise the host system while maintaining performance through warm pools and intelligent resource management.
Sources: design/sandbox.md, CLAUDE.md:46-47

These environments are critical for the "coding-delegation" pipeline, allowing agents like Claude Code to operate within a controlled workspace with kernel-enforced hierarchical resource ceilings.
Sources: changelog.d/2026-04-17-design-drafted-autonomous-coding-container.md, CLAUDE.md:49

Sandbox Architecture

The sandbox system is built on a modular architecture that abstracts specific container runtimes behind a unified client interface. It supports both local execution via Docker/sysbox and remote managed sandboxes via Daytona.
Sources: design/sandbox.md, src/test/daytona-sandbox-fake.test.ts:98-103

The diagram shows the abstraction layer between the Cogmo orchestrator and various execution backends.
Sources: design/sandbox.md, src/sandbox/supervisor.integration.test.ts:16-18

Key Components

Component	Description
Supervisor	Manages the lifecycle of containers, including creation, execution, and cleanup.
Reaper	A cron-based service (running every 30s) that cleans up TTL-expired, orphan, or stale sandbox rows.
LocalDockerSandboxClient	Implementation for running sandboxes on the host using Docker API proxy patterns.
Daytona Client	Interface for interacting with remote Daytona managed sandboxes.
Resource Limits	Kernel-enforced caps on CPU, memory, and PIDs via systemd slices.

Sources: design/sandbox.md, src/sandbox/supervisor.integration.test.ts:24-28, changelog.d/2026-04-17-design-drafted-autonomous-coding-container.md

Data Model and Lineage

Cogmo tracks sandbox state using a set of denormalized tables to maintain lineage and policy at the Docker API level. This ensures that every container can be traced back to a specific task and parent instance.
Sources: design/sandbox.md, changelog.d/2026-04-17-design-drafted-autonomous-coding-container.md

Sandbox Labels

Containers are tagged with specific labels to enable automated management and reaping:

• cogmo.managed=true: Identifies containers created by the system.
• cogmo.instance_id: Links the container to a specific supervisor instance.
• cogmo.root_task_id: Associates the sandbox with the originating task.

Sources: src/sandbox/supervisor.integration.test.ts:108-111

Resource Usage Schema

Telemetry is captured to track the consumption of sandbox resources:
Sources: src/agent/coding/types.ts:79-115

export const ResourceUsageSchema = z.object({
  memory_bytes: z.object({
    managed: z.number().int().nonnegative(),
    user: z.number().int().nonnegative(),
    project: z.number().int().nonnegative(),
  }).optional(),
  cpu_seconds: z.number().nonnegative().optional(),
  sandbox: z.object({
    backend: z.string().min(1),
    created_at: z.string().datetime(),
    deleted_at: z.string().datetime().optional(),
    provisioned: z.object({
      cpu: z.number().nonnegative(),
      memory_bytes: z.number().int().nonnegative(),
    }).strict(),
  }).strict().optional(),
}).strict();

Sources: src/agent/coding/types.ts:88-115

Workspace Management

Sandboxes interact with code through "Worktree Assignments." Depending on the backend, these are handled via host bind-mounts or git-remote operations.
Sources: src/agent/coding/types.ts:27-38

The flow describes how a coding task's working directory is materialized within the sandbox.
Sources: src/agent/coding/types.ts:39-55, src/test/daytona-sandbox-fake.test.ts:114-118

Credential Delivery

Secure credential delivery is handled via GIT_ASKPASS and short-lived Personal Access Tokens (PATs). These are mirrored into the sandbox filesystem through a synthetic directory (e.g., /.cogmo-askpass/) containing helper scripts and the PAT itself.
Sources: changelog.d/2026-04-17-design-drafted-autonomous-coding-container.md, src/test/daytona-sandbox-fake.test.ts:40-48

Lifecycle and Maintenance

The sandbox lifecycle is managed through explicit states: created, running, and reaped.
Sources: src/sandbox/supervisor.integration.test.ts:203-206

The Reaper Process

To prevent resource leakage, a Reaper process executes every 30 seconds to handle:

1. TTL Expiration: Containers that have exceeded their expiresAt timestamp.
2. Orphan Cleanup: Containers whose supervisor instance has crashed (detected via reconcileCrashedInstances).
3. Stale Rows: Cleaning up database entries for containers that no longer exist on the Docker daemon.

Sources: design/sandbox.md, src/sandbox/supervisor.integration.test.ts:219-224, changelog.d/2026-04-17-design-drafted-autonomous-coding-container.md

Execution Flow

Commands are executed within the sandbox using streaming handles that demultiplex stdout and stderr.
Sources: src/sandbox/supervisor.integration.test.ts:145-155

Resource Constraints

Cogmo enforces strict resource caps to prevent sandboxes from exhausting host resources. Default limits are specified as part of the ResourceLimits structure.
Sources: src/sandbox/supervisor.integration.test.ts:24-28

Limit	Typical Default	Enforcement
CPUs	0.5 - 1.0	NanoCpus / CgroupParent
Memory	256MB - 512MB	Memory (bytes)
PIDs	64 - 256	PidsLimit

Sources: src/sandbox/supervisor.integration.test.ts:114-116, src/agent/coding/claude-cli.integration.test.ts:27-31

Execution sandbox environments are a foundational security and operational layer in Cogmo, ensuring that autonomous agents can safely develop and test code while providing full auditability and resource control.