Sandbox Layer

The sandbox layer is the execution boundary between AgentClash orchestration and the environment where an agent actually runs.

Why the sandbox boundary exists

The workflow engine should decide what to run and when to retry. It should not directly own process isolation, filesystem risk, network policy, or provider-specific runtime setup. Those concerns change at a different rate and carry a different failure model.

That is why the architecture keeps a boundary between orchestration and execution:

• the API decides that a run should exist
• Temporal workflows coordinate the lifecycle
• the worker performs execution work
• the sandbox provider supplies isolation for the runnable target

Why E2B is the current fit

E2B is a managed service that runs each agent in its own cloud sandbox (an isolated microVM). It is the concrete sandbox provider in use today. That gives AgentClash a managed isolation layer without having to invent a bespoke container orchestration story inside the app itself.

The main benefits are straightforward:

• isolation is handled outside the web and API processes
• runtime setup is explicit and configurable through worker environment
• the provider can be swapped later without rewriting the product model around runs and evidence

API serverTemporal workflowWorker activitySandbox providerAgent executionReplay events and artifacts

What this boundary protects

This is not only about security. It is also about keeping failure domains honest.

When a run fails, you want to know whether the issue belongs to:

• the scheduler
• the worker logic
• the sandbox provider
• the agent itself

A clean sandbox boundary makes that diagnosis easier because provider setup and execution failures do not get mixed into the same code path as API concerns.

How the provider is selected

The worker picks a sandbox provider from the SANDBOX_PROVIDER environment variable:

• unconfigured (the default) — a noop provider. Runs queue but never execute. This is what the local stack uses until you supply E2B credentials.
• e2b — runs each agent in an E2B sandbox. Requires E2B_API_KEY and E2B_TEMPLATE_ID; the worker fails to start if either is empty. Optional tuning: E2B_API_BASE_URL and E2B_REQUEST_TIMEOUT (default 30s).

Any other value is rejected at worker startup.

For contributors who want the wiring: backend/internal/worker/config.go reads the environment surface above, backend/internal/sandbox/sandbox.go defines the provider interface, and docs/worker/local-development.md covers how the local stack expects the provider to be configured.

Why not bake execution directly into the web or API app

Because that would collapse the concerns that need to stay separate. You would tie request handling, orchestration, and risky execution into the same operational surface. That is faster for a demo and worse for a real evaluation platform.

See also

• Orchestration
• Evidence Loop
• Self-Host
• Config Reference
• Datasets overview
• Security evaluation