Sandbox

Agent Kernel's sandbox capability gives agents a first-class, permission-bounded way to execute code and shell commands, work in a persistent workspace, and read/write files in an isolated environment. When enabled, agents automatically gain a set of sandbox tools and the usage guidance is injected into their system prompt, so your agent code stays free of sandbox mechanics.

Overview

For a deeper look at the internals behind this diagram (class contracts, broker and worker flows, session lifecycle, error hierarchy), see Architecture → Sandbox Internals.

Key design points:

• Self-describing. With sandbox.enabled: true, Agent Kernel attaches the sandbox tools to agents and injects their usage into the system prompt. Your agent's own instructions never need to mention the sandbox.
• Config-driven. Everything — provider, isolation, lifetime, permissions, identity — is chosen in config.yaml through workload profiles. No code changes to switch backends.
• Pluggable and honest. Providers are selected by short name or a dotted path to your own SandboxProvider subclass. Each provider declares the capabilities it actually supports (isolation tier, shell, files, policy enforcement, user identity); Agent Kernel never pretends two backends are interchangeable on security grounds.
• Fail closed. A permission or identity requirement a provider cannot honor is rejected under strict mode, never silently downgraded.

No isolation with local_subprocess

The default demo provider, local_subprocess, runs code directly on the host with no isolation. It is for development and testing only. Production deployments should use an isolating provider such as docker.

Enabling the sandbox

Add a sandbox block to config.yaml. The minimal form uses the single-backend sugar — set a type and its config block, and a default profile is synthesized for you:

sandbox:
  enabled: true
  type: local_subprocess       # provider short name (or a dotted path to your own provider)
  local_subprocess: {}         # the provider's config block
  broker:
    flavor: thread             # local default; see Broker flavors

Everything is inert when sandbox.enabled is false (the default): no tools are attached, no hooks run, and no provider dependencies are imported.

Agent tools

When enabled, every in-scope agent gains eight tools. All return JSON strings; the execution and file tools echo a sandbox_session_id (the session tools return session lists/ids and check_sandbox_task its status). Machinery failures come back as {"error": ...} rather than raising.

Tool	Purpose
run_code(code, language, sandbox_session_id, profile)	Execute code; returns stdout, stderr, exit_code.
run_command(command, sandbox_session_id, profile)	Execute a shell command.
write_sandbox_file(path, content, sandbox_session_id, profile)	Write a UTF-8 text file into the workspace.
read_sandbox_file(path, sandbox_session_id, profile)	Read a UTF-8 text file (truncated to tool_output_max_chars).
check_sandbox_task(task_id)	Poll a long-running execution that returned status: pending.
list_sandbox_sessions()	List the sandbox sessions in the conversation (id, name, profile, status).
new_sandbox_session(name, profile)	Create a fresh, empty session; returns its sandbox_session_id.
destroy_sandbox_session(sandbox_session_id)	Destroy a session and its sandbox.

tool_output_max_chars (default 8000) bounds how much stdout/stderr or file content is returned to the model.

Restricting tools to specific agents

By default the tools attach to all agents. To limit them to named agents, set agents:

sandbox:
  enabled: true
  agents: [coder, data_analyst]   # only these agents get the sandbox tools + prompt
  type: local_subprocess
  local_subprocess: {}

Omit agents for the current "all agents" behavior; an empty list attaches to none.

Workload profiles

A profile bundles a provider, a lifetime (scope), a permission policy, and an identity mode. Agents pick a profile per call via the profile= argument; the injected guidance lists the configured profiles. Define them explicitly for multi-profile setups:

sandbox:
  enabled: true
  default_profile: workspace
  profiles:
    workspace:                 # persistent, for multi-step work
      type: local_subprocess
      scope: per_session
      idle_timeout: 21600      # 6 hours
      local_subprocess: {}
    scratch:                   # throwaway, one sandbox per execution
      type: local_subprocess
      scope: per_call
      local_subprocess: {}
  broker:
    flavor: thread

Scopes

Scope	Lifetime	Use for
per_session (default)	One sandbox per AK session; workspace persists across turns.	Multi-step work, notebooks, iterative coding.
per_call	A fresh sandbox per execution, torn down immediately after.	One-off, stateless computations.
per_runtime	A single shared sandbox per profile, process-wide.	Shared warm environments (executions serialized; no pooling in v1).

Sessions

Each sandbox is addressed by a sandbox_session_id. State (files, workspace) persists per id: the agent reuses the id from a previous result to continue in the same environment, or omits it for the profile's default session. Session ids are system-assigned — the agent creates new ones with new_sandbox_session (optionally naming them) and finds earlier ones with list_sandbox_sessions, rather than inventing ids.

Sessions belonging to one AK session are namespace-isolated: they live in that session's non-volatile cache, so one conversation can never address another's sandboxes. (per_runtime is the deliberate exception — a single shared entry per profile in process memory.)

Idle timeout and recreation notices

Every profile has an idle_timeout (default 1800 s). When a session is touched after being idle past that window, its sandbox is reset (workspace discarded) and recreated under the same id. The same recreation happens if a backend sandbox has vanished (self-heal). Either way the reset is surfaced to the agent as a notice field on the result, and the injected guidance tells the agent to relay it — so a wiped workspace is reported, never silently hidden.

(For environment: attached profiles the semantics differ deliberately — see the next section: expiry only drops the session binding, and a vanished target is never recreated.)

Managed vs attached environments

Every profile declares its environment lifecycle — who owns the thing code runs in:

profiles:
  ec2:
    type: ec2_ssm
    environment: attached        # managed (default) | attached
    ec2_ssm:
      attach_to: i-0123456789abcdef0

• managed (default): the provider creates the sandbox and the framework owns its lifecycle end to end — creation, idle reset, self-heal recreation, destruction.
• attached: the framework deliberately connects to an environment that already exists and never owns it — an EC2 instance over SSM, an existing container, a runtime you operate. This is an explicit opt-in: pointing agents at a live system must be a deliberate configuration choice, never a side effect.

The mode is validated at startup against the provider's declared lifecycle capabilities (provisions / attaches_external), in both directions:

Profile mode	Provider can only provision (e2b, daytona, local_subprocess)	Provider supports both (docker, kubernetes)	Provider is attach-only (ec2_ssm)
managed (default)	OK	OK (attach_to must be unset)	rejected — attach-only providers require environment: attached
attached	rejected — cannot attach to an existing environment	OK (attach_to required)	OK (attach_to required)

Setting attach_to under a managed profile is also rejected, so the deliberate-choice rule cannot be bypassed.

attached changes the runtime rules to match non-ownership:

• Never destroyed. destroy_sandbox_session (and idle expiry) only drop the session binding; the environment itself is untouched.
• Never recreated. If the attached target becomes unreachable, the failure is surfaced as an error instead of the managed self-heal (which would silently provision a fresh sandbox that is not your system).
• Idle notices say so. An expired attached session reports that its binding was reset and the environment is untouched, instead of "workspace state was discarded".

Policy and permissions

A profile's policy block is the permission and resource envelope for an execution:

profiles:
  guarded:
    type: docker
    scope: per_session
    policy:
      network_egress: deny        # allow | deny | allowlist
      network_allow: []           # domains/CIDRs when egress is 'allowlist'
      fs_allow_read: []           # filesystem paths readable (empty = provider default)
      fs_allow_write: []          # filesystem paths writable
      cpu: 1.0                    # CPU cores
      memory_mb: 512              # memory limit (MB)
      timeout: 30.0               # per-execution wall-clock seconds (always enforced)
      strict: true                # fail closed on unenforceable dimensions
    docker:
      image: python:3.12-slim

Enforcement is per-provider, and unenforceable is not the same as ignored. Each provider declares which policy dimensions it can enforce. When a profile sets a non-default dimension the provider cannot enforce:

• strict: true (default) → the execution is rejected with a policy error. Security is never silently downgraded.
• strict: false → it proceeds, with a one-time warning naming the unenforced dimensions.

timeout is always enforceable (framework-side), so it never triggers a strict rejection.

Identity

Sandboxed code can run under the agent's identity or the invoking user's identity. Two settings drive this:

• profile.identity.mode — agent (default) or user.
• sandbox.principal_resolver — a dotted path to a PrincipalResolver that maps the current session/agent to a SandboxPrincipal. Omitted → the built-in AgentPrincipalResolver (the agent's own identity).

sandbox:
  enabled: true
  principal_resolver: myapp.identity.SessionUserPrincipalResolver
  profiles:
    secure:
      type: myapp.providers.MyIdentityProvider   # a provider that declares principal_user=True
      identity:
        mode: user

The shipped local_subprocess and docker providers declare principal_user=False, so identity.mode: user on them is rejected. Two shipped providers support user identity:

• kubernetes maps a user-mode principal onto RBAC impersonation headers: Impersonate-User from credentials["user"] (falling back to the principal's subject) and at most one Impersonate-Group from credentials["groups"] (or the principal's groups); the Python client cannot send repeated group headers, so more than one group is rejected fail-closed. The API server then enforces the invoking user's own RBAC on pod creation, exec, and per-pod NetworkPolicies; impersonating clients are cached per (user, groups). Two operational notes: the worker's own identity must hold the cluster-scoped impersonate verb (the ak-k8s chart gates this behind sandboxWorker.rbac.impersonate), and disposal (destroy, the idle sweep) runs under the worker's own identity because it is a platform action with no user in context.
• ec2_ssm assumes credentials["role_arn"] via sts:AssumeRole and runs commands as credentials["run_as"] when set (see the provider table).

A bring-your-own provider (dotted path) can implement any other mapping.

The resolver runs agent-side (it has the session in context); the resolved principal travels in the broker request and is enforced provider-side where the credentials live. Fail-closed rule: a user-mode profile requires both a provider that supports user identity and a resolver that actually returned a user-mode principal — otherwise the execution is rejected. A user-scoped request can never silently fall back to the agent identity.

See the end-to-end identity example for a REST app that authenticates each request and runs code under the caller's identity.

Providers

Providers are selected per profile by type. Each declares an honest isolation tier so you know the boundary you are getting:

Tier	Boundary
none	No isolation boundary (host process).
os_policy	OS-level confinement (seccomp/Seatbelt/bubblewrap).
container	Shared-kernel namespaces (containers).
syscall_filter	User-space kernel (gVisor-style).
micro_vm	Firecracker / managed micro-VM.
wasm	In-process WebAssembly runtime.

Providers available today:

Provider	Extra	Isolation	Notes
local_subprocess	— (stdlib)	none	Runs on the host. Dev/test only. Shell + files + python/bash.
docker	sandbox-docker	container	Container per sandbox (sleep infinity); files via archives; pip install. Maps deny→network_mode: none, cpu/memory→limits, fs→read-only rootfs + writable workdir. Requires a Docker daemon.
e2b	e2b	micro_vm	Managed Firecracker micro-VMs on the E2B cloud (native async SDK). Stateful Jupyter-kernel execution (variables persist across calls); shell, files, pip install. Maps deny→no internet access, allowlist→allow_out network rules; the profile's idle_timeout becomes E2B's native auto-kill timeout. Needs E2B_API_KEY (name configurable via api_key_env).
daytona	daytona	container	Container sandboxes on the Daytona cloud (sync SDK via to_thread). Shell, files, pip install. Maps deny→block-all, allowlist→CIDR allow list, cpu/memory→Resources (image-based sandbox); idle_timeout becomes Daytona's native auto_stop_interval. Needs DAYTONA_API_KEY (name configurable via api_key_env).
ec2_ssm	aws	none	Attach-only (requires environment: attached): executes on an existing EC2 instance via SSM Run Command — binds to attach_to, never provisions or disposes. Shell + python (heredoc); no policy enforcement beyond the execution timeout. Supports user identity (sts:AssumeRole + optional run_as OS user). No persistent shell: each command is its own process, so cwd/env/sudo su do not carry across commands (stateful=False); chain dependent steps (cd /app && ./run.sh).
kubernetes	kubernetes	container	Pod per sandbox (sleep infinity) via the Kubernetes API; exec over the stream API, files as tar streams, pip install. Hardened container defaults (no privilege escalation, seccomp RuntimeDefault, all capabilities dropped) under your security_context overlays. Maps cpu/memory→requests=limits, fs→read-only rootfs + emptyDir workdir, and egress→per-pod NetworkPolicies only when network_policy: true asserts the cluster CNI enforces them. Supports user identity via RBAC impersonation (see Identity). Pods carry activeDeadlineSeconds = 2 × idle_timeout as the orphan ceiling; the pod ServiceAccount's RBAC is the security boundary.

Additional providers (bedrock_agentcore) are planned in later iterations.

docker setup

pip install "agentkernel[sandbox-docker]"

sandbox:
  enabled: true
  type: docker
  docker:
    image: python:3.12-slim     # any image with python
  broker:
    flavor: thread

e2b setup

pip install "agentkernel[e2b]"
export E2B_API_KEY=e2b_...

sandbox:
  enabled: true
  type: e2b
  e2b:
    template: base              # E2B sandbox template
    # api_key_env: E2B_API_KEY  # env variable holding the API key
  broker:
    flavor: thread

daytona setup

pip install "agentkernel[daytona]"
export DAYTONA_API_KEY=dtn_...

sandbox:
  enabled: true
  type: daytona
  daytona:
    image: python:3.12-slim         # container image for the sandbox...
    # snapshot: my-warm-snapshot    # ...OR a named Daytona snapshot (mutually exclusive)
    env_vars:                       # environment variables set inside the sandbox
      APP_ENV: demo
    # target: us                    # Daytona target/region; omitted = SDK default
    # api_key_env: DAYTONA_API_KEY  # env variable holding the API key
  broker:
    flavor: thread

A sandbox launches from one base — an image or a snapshot, never both (neither = Daytona's default snapshot). Resource limits (policy.cpu / policy.memory_mb) only attach to an image-based sandbox, so a resource policy forces the image path (using your image, or python:3.12-slim if unset); pinning both a snapshot and resource limits is rejected.

kubernetes setup

profiles:
  cluster:
    type: kubernetes
    kubernetes:
      namespace: sandboxes            # where sandbox pods run
      image: python:3.12-slim         # substitute your hardened image in production
      service_account: sandbox-pod    # the pods' identity; its RBAC is the security boundary
      kubeconfig: null                # null = in-cluster config, then the default kubeconfig
      network_policy: false           # true only when the cluster CNI enforces NetworkPolicy

Install with pip install "agentkernel[kubernetes]".

RBAC is the boundary, never command parsing. What sandboxed code may do against the cluster is decided by the ServiceAccount assigned to sandbox pods and enforced by the API server: bind it to view for read-only kubectl, or to nothing for pure compute. A "read-only command filter" is not a boundary and Agent Kernel never implements one. The calling process (the broker worker, or the agent process on in-process flavors) needs pod-lifecycle verbs plus both create and get on pods/exec (WebSocket exec is a GET); the ak-k8s chart's sandboxWorker.rbac renders exactly this.

network_policy: true flips the provider's policy_network capability per instance and maps deny/allowlist egress onto per-pod NetworkPolicies (CIDR entries only; domain names fail closed under strict). Set it only when the cluster's CNI actually enforces NetworkPolicy: the provider cannot detect that, so it is an operator assertion.

ec2_ssm setup

pip install "agentkernel[aws]"

sandbox:
  enabled: true
  type: ec2_ssm
  environment: attached             # required: ec2_ssm is attach-only (deliberate opt-in)
  ec2_ssm:
    attach_to: i-0123456789abcdef0  # existing instance id (or via AK_SANDBOX__... env override)
    # region: us-east-1             # omitted = boto3 default
  broker:
    flavor: thread

The instance must run the SSM agent, and the caller needs ssm:SendCommand, ssm:GetCommandInvocation, ssm:DescribeInstanceInformation, and ssm:CancelCommand. Isolation is none: commands run directly on the instance, so attach only to hosts you own. In user-identity mode the provider assumes the principal's role_arn and, when run_as is set, executes commands as that OS user.

Bring your own provider

Any dotted path to a SandboxProvider subclass works as a type, so you can plug in a backend Agent Kernel doesn't ship. For attach-only backends (an environment you own that the framework should connect to but never create or dispose), subclass AttachedEnvironmentProvider instead: it fixes the non-ownership lifecycle (create binds to the configured attach_to, destroy is a no-op) so you implement only attach, returning an AttachedEnvironment handle (the Sandbox subclass for targets the framework never owns, whose close() is likewise fixed as a no-op). Profiles selecting such a provider must declare environment: attached.

profiles:
  custom:
    type: mypackage.providers.MyProvider   # your SandboxProvider subclass
    scope: per_session
    params:                                 # validated by your provider's config_model, if any
      endpoint: https://sandboxes.internal

Subclass SandboxProvider (and Sandbox), declare capabilities, and implement create and destroy (plus attach when you declare capabilities.attach, and the operations your capabilities advertise). The reusable SandboxProviderContract test suite (in agentkernel.sandbox.testing) asserts the ABC semantics your provider must honor.

Broker flavors

The broker decouples the agent from execution. It is chosen with sandbox.broker.flavor:

Flavor	Where it runs	Use for
thread (default)	A dedicated daemon thread + event loop in the agent process.	CLI and REST deployments.
embedded	Inline in the caller's event loop (always synchronous).	Simple/co-located execution and tests.
queue	A separate worker fleet (QueueBrokerWorker), decoupled by any queue transport (in_memory, sqs, kafka, nats).	Executions longer than the agent runtime allows, cluster-side worker tiers, Lambda/ECS agents with a remote worker.

wait_timeout (default 60 s) bounds how long a synchronous call waits before the execution is promoted to a background task (thread flavor): run_code/run_command then return {"status": "pending", "task_id": ...}, and the agent polls with check_sandbox_task. wait_timeout: 0 always promotes. The embedded flavor is always synchronous and never promotes, so wait_timeout does not apply to it.

The queue flavor

flavor: queue moves execution out of the agent process entirely. The client sends each request over the sandbox.broker.queue block's input queue (the same shape and transports as execution.queues; group_id = sandbox_session_id keeps one execution in flight per sandbox session across the whole worker fleet). A QueueBrokerWorker executes it and returns the completion over the block's output queue, where the worker's own output loop persists it to the shared sandbox.broker.response_store. The client polls that store for the bounded wait; on this flavor wait=None is bounded by wait_timeout, and expiry promotes to a pending task.

Recovery is wait-then-check. There are no completion events and no agent re-invocation: when a turn ends with a pending task, check_sandbox_task on a later turn returns the finished task's status and its bounded output. destroy is fire-and-forget (per-session FIFO ordering makes that safe).

At-least-once semantics. A worker that dies mid-execution has the request redelivered up to queue.input.max_receive_count deliveries, after which a permanent-failure completion is recorded; side-effectful commands are therefore not exactly-once. Size the transport's visibility window above your largest profile policy.timeout (NATS ack_wait, the SQS visibility timeout), or a still-running execution is redelivered and runs twice. Once a completion has been queued, a response-store outage only retries the persist, never the execution. The worker also sweeps managed sandboxes idle past their profile's idle_timeout when the response store supports key scans (all four built-ins do).

The worker is a public entry point, run wherever the sandbox backends live:

from agentkernel.sandbox import QueueBrokerWorker

QueueBrokerWorker.run()

Both target topologies ship as examples: sandbox/broker-kafka (agents outside the cluster, e.g. Lambda or ECS, with the worker beside it) and sandbox/broker-nats (everything in-cluster via the ak-k8s chart's sandboxWorker tier, including its standalone worker-only install); see the chart README's sandbox worker section for KEDA scaling and namespace hardening.

Configuration reference

The sandbox block, with defaults:

sandbox:
  enabled: false                 # master switch
  agents: null                   # list of agent names to attach to; null = all agents
  default_profile: default       # profile used when a call omits profile=
  principal_resolver: null       # dotted path to a PrincipalResolver; null = AgentPrincipalResolver
  tool_output_max_chars: 8000    # truncation limit for tool output

  broker:
    flavor: thread               # thread | embedded | queue | dotted path
    wait_timeout: 60.0           # seconds before a sync wait promotes to a task (0 = always promote);
                                 #   on the queue flavor this also bounds wait=None
    wait_poll_interval: 0.5      # queue flavor: seconds between response-store polls
    inline_payload_max_bytes: 131072   # queue flavor: request rejection + result truncation limit
    response_ttl: 86400          # queue flavor: TTL for completion and inventory records
    sweep_interval: 300          # queue flavor: seconds between idle-session sweeps
    worker_timeout_ceiling: null # queue flavor: reject policy timeouts above the worker's runtime limit
    queue: null                  # queue flavor: the sandbox queues (the execution.queues shape;
                                 #   input carries requests, output returns completions)
    response_store: null         # queue flavor: the shared response store (execution shape, required);
                                 #   its ttl fields are overridden by response_ttl

  profiles:                      # named workload profiles
    <name>:
      type: local_subprocess     # provider short name or dotted path (required)
      scope: per_session         # per_call | per_session | per_runtime
      idle_timeout: 1800         # seconds of inactivity before reset-on-touch
      identity:
        mode: agent              # agent | user
      policy:
        network_egress: allow    # allow | deny | allowlist
        network_allow: []
        fs_allow_read: []
        fs_allow_write: []
        cpu: null                # CPU cores
        memory_mb: null          # memory limit (MB)
        timeout: 120.0           # per-execution wall-clock seconds
        strict: true             # fail closed on unenforceable policy
      params: {}                 # passed to a dotted-path (BYO) provider
      # ...one provider config block matching `type`, e.g.:
      local_subprocess:
        workdir: null            # base dir for per-sandbox working dirs; null = system temp
      docker:
        image: python:3.12-slim
        runtime: docker
        attach_to: null          # existing container id to attach to (mode 3)
      kubernetes:
        namespace: default
        image: python:3.12-slim
        service_account: null    # ServiceAccount for sandbox pods (their RBAC boundary)
        kubeconfig: null         # null = in-cluster config, then the default kubeconfig
        attach_to: null          # existing '<namespace>/<pod>' to attach to (mode 3)
        network_policy: false    # per-pod egress NetworkPolicies (CNI must enforce them)
        create_timeout: 120.0    # seconds for a pod to reach Running
        labels: {}               # merged onto sandbox pods
        env: {}                  # container environment variables
        node_selector: {}
        image_pull_secrets: []
        security_context: {}     # pod-level overlay
        container_security_context: {}   # overlays the hardened defaults

  # Single-backend sugar (used only when `profiles` is empty): synthesizes profiles[default_profile]
  type: null                     # provider short name or dotted path
  scope: null                    # scope for the synthesized profile
  local_subprocess: null         # (and the other provider config blocks)

All fields are overridable by environment variables with the AK_ prefix and __ nesting, e.g. AK_SANDBOX__ENABLED=true, AK_SANDBOX__BROKER__FLAVOR=embedded, AK_SANDBOX__TOOL_OUTPUT_MAX_CHARS=4000.

Examples

• sandbox/basic — enable the sandbox, run code, persist a workspace, manage named sessions.
• sandbox/profiles — multiple profiles with different scopes; the agent routes per call.
• sandbox/policy — policy/permissions on the docker provider: an enforced envelope plus the fail-closed strict model for what docker cannot enforce.
• sandbox/docker — the docker provider: container-isolated execution with policy actually enforced (network_egress: deny → no network).
• sandbox/daytona — the daytona provider: cloud container sandboxes with enforced network and resource policy (needs a Daytona API key).
• sandbox/e2b — the e2b provider: Firecracker micro-VM sandboxes with a stateful Jupyter kernel and enforced network policy (needs an E2B API key).
• sandbox/identity — a REST app running sandboxed code under the authenticated end user's identity, end-to-end.
• sandbox/ec2-ssm — the ec2_ssm provider attaching to an existing EC2 instance over SSM (manual; needs a real instance).
• sandbox/broker-kafka — the queue broker flavor over Kafka: a worker running read-only kubectl pods in kind, RBAC as the boundary, bounded waits and check_sandbox_task recovery (needs Docker, kind, kubectl).
• sandbox/broker-nats — the queue broker fully in-cluster: pipeline plus sandbox worker deployed by the ak-k8s chart over NATS, sandbox pods in a hardened namespace (needs a micro-cluster and Helm).