Agent Sandbox

What’s New →

This project has moved from the spring-ai-community GitHub organization to markpollack. New releases are published under the Maven groupId io.github.markpollack, and Java packages now use the io.github.markpollack namespace. If you previously used org.springaicommunity, update your dependency coordinates and imports to the current values shown below.

Agent Sandbox provides one synchronous command and workspace-file contract across multiple backends. The shared exec and file behavior is tested by the AbstractSandboxTCK. Backend-specific or unsupported capabilities, including interactive execution, are not interchangeable.

Backends

LocalSandbox

Process and workspace convenience via zt-exec. It provides no security isolation and is for development and trusted commands.

DockerSandbox

A convenient local Docker backend using Testcontainers and an image you select. It is not a hardened multi-tenant execution service.

E2BSandbox

Remote Firecracker microVM execution via E2B. This backend requires an E2B account and API key.

DockerSandbox has privileged access to a trusted, root-equivalent local Docker daemon. Container isolation alone is not a complete hostile-workload security boundary; add the kernel, user, and network controls required by your threat model.

Core API

try (Sandbox sandbox = LocalSandbox.builder()
        .tempDirectory("test-")
        .build()) {

    // Execute commands
    ExecResult result = sandbox.exec(ExecSpec.of("mvn", "test"));

    if (result.success()) {
        System.out.println(result.stdout());
    }

    // File operations
    sandbox.files()
        .create("pom.xml", pomContent)
        .create("src/main/java/App.java", code)
        .and()    // return to Sandbox
        .exec(ExecSpec.of("mvn", "compile"));
}

Module Structure

Module	Backend	Dependencies
`agent-sandbox-core`	`LocalSandbox`	zt-exec
`agent-sandbox-docker`	`DockerSandbox`	Testcontainers
`agent-sandbox-e2b`	`E2BSandbox`	jackson, awaitility

Maven

The currently released version is 0.10.2:

<dependency>
  <groupId>io.github.markpollack</groupId>
  <artifactId>agent-sandbox-core</artifactId>
  <version>0.10.2</version>
</dependency>

Use agent-sandbox-docker or agent-sandbox-e2b for those backends.

In version 0.10.0, DockerSandbox requires an explicit caller-selected image: the no-argument constructor is removed, and DockerSandbox.builder().build() fails before Docker access unless .image(...) is set. Constructors that already take an image continue to work. The caller may use any compatible image and owns its provenance, contents, security, and update policy.

Source

GitHub

Source code — Core, Docker, and E2B modules

Used By

Agent Judge — agent-judge-exec runs command-based evaluation in sandboxes

Projects

AgentWorks

Supporting Projects

Migration

Backends

LocalSandbox

DockerSandbox

E2BSandbox

Core API

Module Structure

Maven

Source

GitHub

Used By

​Backends

LocalSandbox

DockerSandbox

E2BSandbox

​Core API

​Module Structure

​Maven

​Source

GitHub

​Used By

Backends

Core API

Module Structure

Maven

Source

Used By