C4 Level 3: Execution and Sandboxes

Status: Current code-derived model
Code baseline: release/v0.13.0 (890e1ad)
Last verified: 2026-07-25

Deep Agents receives one backend interface even though commands and files can be served by several systems. Cognition selects a default sandbox for ordinary workspace paths and overlays virtual registry/artifact routes through a composite backend.

Execution component diagram

C4Component
    title Execution and sandbox components

    Container_Boundary(server, "Cognition server") {
        Component(factory, "create_cognition_agent", "Runtime factory", "Builds composite backend for one Agent runtime")
        Component(selector, "create_sandbox_backend", "Backend factory", "Selects one execution adapter")
        Component(composite, "CompositeBackend", "Deep Agents router", "Routes virtual paths or falls through to sandbox")
        Component(artifacts, "ArtifactBackend", "Virtual filesystem", "Exposes versioned content routes")
        Component(local, "Local sandbox", "LocalShellBackend", "Runs under the server OS identity")
        Component(docker, "Docker sandbox adapter", "FilesystemBackend + DockerExecutionBackend", "Host file operations and container commands")
        Component(k8s, "Kubernetes sandbox adapter", "langchain-k8s-sandbox", "Creates and uses agent-sandbox resources")
        Component(microvm, "Lambda MicroVM adapter", "langchain-aws-lambda-microvms", "Creates and uses AWS-isolated runtime")
        Component(manager, "SessionAgentManager", "Lifecycle manager", "Tracks sandbox correlation, events, quotas, abort, and teardown")
    }

    ContainerDb(config, "Config and artifact stores", "Scoped definitions and content")
    System_Ext(docker_engine, "Docker Engine", "Creates sibling containers")
    System_Ext(k8s_platform, "Kubernetes sandbox platform", "API, controller, router, and sandbox pods")
    System_Ext(aws, "AWS Lambda MicroVM service", "Control API and authenticated runtime proxy")

    Rel(factory, selector, "Requests selected sandbox")
    Rel(factory, composite, "Creates")
    Rel(composite, artifacts, "Routes artifact namespaces")
    Rel(artifacts, config, "Reads/writes versions")
    Rel(composite, local, "Default when selected")
    Rel(composite, docker, "Default when selected")
    Rel(composite, k8s, "Default when selected")
    Rel(composite, microvm, "Default when selected")
    Rel(docker, docker_engine, "Creates/executes in container")
    Rel(k8s, k8s_platform, "Claims, executes, transfers, terminates")
    Rel(microvm, aws, "Runs MicroVM and calls runtime endpoints")
    Rel(manager, local, "Tracks")
    Rel(manager, docker, "Tracks")
    Rel(manager, k8s, "Tracks and terminates")
    Rel(manager, microvm, "Tracks, enforces quota, terminates")

Composite filesystem

The runtime's default backend is the selected sandbox. When configuration and artifact stores are available, the factory overlays these virtual routes:

Path	Backend	Meaning
/scratch/	ArtifactBackend	Versioned scratch content
/artifacts/	ArtifactBackend	General artifacts
/contracts/	ArtifactBackend	Structured contracts
/evals/	ArtifactBackend	Evaluation artifacts
/memories/	ArtifactBackend	Persisted memory content
/policies/	ArtifactBackend	Policy artifacts
All other paths	Selected sandbox	Workspace files and commands

Artifact writes create a new version. Skills are builder-mounted beneath the selected sandbox workspace's skills/ directory and Deep Agents discovers them through the sandbox backend. Scope is passed to durable virtual backends.

Sandbox choices

Local

CognitionLocalSandboxBackend extends Deep Agents' local shell backend. Commands run with the Cognition server's OS identity and filesystem access. Per-session workspace directories improve separation and protected-path checks guard direct file writes, but local execution is not a process, kernel, or network isolation boundary.

Docker

CognitionDockerSandboxBackend uses host-side filesystem operations and lazily creates a container for commands. DockerExecutionBackend configures:

• A read-only container root
• Builder-configured workspace root, /tmp, and /home
• All Linux capabilities dropped
• no-new-privileges
• Configured CPU and memory limits
• Configured network mode, defaulting to none

The workspace is mounted read/write, so the container can modify session files. The command path uses sh -c inside the container because arbitrary shell execution is the intended sandbox capability.

Kubernetes

CognitionKubernetesSandboxBackend delegates to the workspace package langchain-k8s-sandbox. It lazily creates or claims an agent-sandbox Sandbox resource, optionally uses a warm pool, verifies the runtime, applies a shutdown time, and sends command/file requests through the sandbox platform.

The Cognition pod requires namespaced sandbox permissions and read access to the Sandbox custom resource definition. A network policy can deny sandbox egress. The sandbox image runs the command/file server independently of the Cognition server.

AWS Lambda MicroVM

CognitionAwsLambdaMicroVmSandboxBackend resolves a trusted SandboxProfile and delegates lifecycle and file/command calls to langchain-aws-lambda-microvms. Profiles can select image/version, region, execution role, connectors, lifetime, idle policy, logging, and quota.

The adapter starts a MicroVM through the AWS SDK, obtains an in-memory runtime authorization token, waits for health, and calls the authenticated runtime proxy. Lifecycle metadata deliberately omits the token and records a role fingerprint instead of exposing the role value in every signal.

Lifecycle ownership

SessionAgentManager stores process-local mappings from session IDs to services, active runtime handles, and sandbox objects. It emits sandbox lifecycle events, supports abort, applies MicroVM quota checks, and calls terminate() on backends that implement it when a session is released.

Kubernetes and MicroVM adapters implement explicit termination. The current Docker wrapper does not expose terminate(), so its container lifecycle is not closed through the same manager path.

Integration branch: explicit release observations

The internal SessionAgentManager.release_sandbox_backend returns complete only when its tracked backend has been removed after teardown confirmation. It returns pending for an in-flight or unconfirmed attempt, including provider failures that retain a retryable handle. It returns untracked when this process has no handle. Existing callers may ignore this additive result.

This operation does not delete session history. The result is an observation of one process-local attempt, not a durable receipt: a repeat after completion can return untracked, as can a call to another replica or after a restart. Callers must not interpret untracked as provider termination or permission to erase storage. This change does not expose a public release endpoint or revoke future session execution; a scoped cutover contract remains implementation work.

Integration branch: pinned profile admission

Lambda sandbox construction now resolves the selected profile from the live registry under the current trusted scope even when a run carries a pinned profile. A missing or changed profile rejects construction before backend acquisition. Unchanged pins retain their behavior. This prevents historical manifests from silently restoring deleted or modified infrastructure configuration. Existing sessions and history are retained; affected resumes fail admission.

This is admission at Agent construction, not immediate revocation of an already running VM or distributed fencing. Scoped release and complete cutover remain separate work. Unit tests cover deleted, changed and foreign-scope profiles and unchanged pinned-profile backend reuse.

Security properties and limits

Property	Local	Docker	Kubernetes	Lambda MicroVM
Separate kernel boundary	No	Yes	Yes	Yes
Separate process boundary	No	Yes	Yes	Yes
Network policy	Server's network	Docker network mode	Platform/network policy	Profile connectors
Resource limits	Server limits	CPU/memory settings	Sandbox template	Service/profile quota
Explicit teardown in adapter	Not required	Not currently exposed	Yes	Yes
Protected direct-write paths	Yes	Host filesystem policy differs	Yes	Yes
Appropriate for untrusted commands	No	Depends on host hardening	Depends on sandbox platform	Depends on profile/platform

Protected-path checks apply to direct backend write/edit methods; they do not make arbitrary shell commands safe. API-registered Python tools are loaded in the Cognition server process, so their trust boundary is the protected builder administrative API—not the command sandbox.

Current Docker execute(timeout=...) accepts a timeout argument but does not apply it to exec_run. This is a known operational constraint.

Code evidence

Responsibility	Primary source
Composite backend creation	server/app/agent/cognition_agent.py — create_cognition_agent
Sandbox selection and wrappers	server/app/agent/sandbox_backend.py
Docker container configuration	server/app/execution/backend.py
Kubernetes adapter package	packages/langchain-k8s-sandbox/langchain_k8s_sandbox/sandbox.py
Lambda MicroVM adapter package	packages/langchain-aws-lambda-microvms/langchain_aws_lambda_microvms/sandbox.py
Native Skills directory	<sandbox workspace_root>/skills, passed to Deep Agents by server/app/agent/cognition_agent.py
Artifact virtual filesystem	server/app/agent/artifacts_backend.py
Sandbox lifecycle ownership	server/app/llm/deep_agent_service.py — SessionAgentManager
Per-session workspace	server/app/session_manager.py
Kubernetes runtime image/API	Dockerfile.sandbox; deploy/sandbox/runtime_server.py

Related views

• Agent runtime components
• Runtime flows
• Deployment and operations

Idle-only release admission

The session manager supports release_sandbox_backend(session_id, only_if_idle=True) for compute reclamation without aborting registered local runtime work. Its existing ownership lock checks activity and admits teardown atomically against local runtime registration. Active work returns busy; idle work follows the existing complete, pending, or untracked observations. The default remains unchanged for explicit abort/deletion callers. This internal primitive neither deletes history nor establishes cross-replica idleness; scoped HTTP admission and persisted session/run checks remain necessary before an administrative endpoint can use it.

The scoped POST /sessions/{session_id}/sandbox/release endpoint now applies exact session lookup and persisted session/run activity checks before idle-only manager release. Its observation is limited to the tracked backend on the serving process. It does not prove all replicas or all mounts for a storage binding are gone, and an untracked retry remains uncertain.