Agent-Sandbox: Enterprise-Grade Sandbox for AI Agents on Kubernetes

Introduction

Agent-Sandbox is an easy-to-use, enterprise-grade sandbox platform specifically designed for AI Agents. It addresses the critical challenge of securely running untrusted, LLM-generated code and actions. With Agent-Sandbox, AI agents can safely perform tasks like code execution, browser use, computer use, and even deploy websites, all within isolated environments.

The platform ensures multi-session and multi-tenant isolation, preventing one agent's runaway task from affecting another. While built upon the robust Kubernetes foundation, similar to kubernetes-sigs/agent-sandbox, Agent-Sandbox simplifies interaction by wrapping this complexity behind a user-friendly RESTful API and an MCP server. This design allows agents and developers to create, use, and delete sandboxes without direct Kubernetes interaction, drawing inspiration from platforms like Blaxel Sandbox and E2B, but offering an open-source, self-hosted solution.

Installation

To get started with Agent-Sandbox, you will need a Kubernetes cluster running version 1.28 or higher. The installation process is straightforward, involving a single command to apply the provided install.yaml file.

First, create a dedicated namespace for Agent-Sandbox:

kubectl create namespace agent-sandbox

Then, apply the installation manifest:

kubectl apply -nagent-sandbox -f https://github.com/agent-sandbox/agent-sandbox/blob/main/install.yaml

After installation, you can expose the Agent-Sandbox API server using an Ingress. Here is an example configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: agent-sandbox
  namespace: agent-sandbox
spec:
  ingressClassName: ingress-nginx
  rules:
  - host: agent-sandbox.your-host.com
    http:
      paths:
      - backend:
          service:
            name: agent-sandbox
            port:
              number: 80
        path: /

Once the Ingress is configured, the Agent-Sandbox API server will be accessible at http://agent-sandbox.your-host.com.

Examples

Agent-Sandbox offers full E2B protocol and SDK compatibility, making it a drop-in replacement for existing E2B-based agents and tools. Here is an example of how to use it with the E2B Python SDK.

Requirements:
Ensure you have the following Python packages installed:

e2b == 2.21.1
e2b-code-interpreter == 2.4.1

Configure the E2B backend address:
Set the necessary environment variables to point to your Agent-Sandbox instance:

export E2B_API_KEY=testuser-aef134ef-7aa1-945e-9399-7df9a4ad0c3f
export E2B_DOMAIN=agent-sandbox.your-host.com
export E2B_API_URL=http://agent-sandbox.your-host/e2b/v1

Python example:
This Python script demonstrates creating a sandbox, running a background command, creating a snapshot, and uploading a file.

from e2b_code_interpreter import Sandbox

idleTimeout = 60*10

# Create a sandbox instance from the "sandbox-base-node" template,
# with an idle timeout of 10 minutes,
# a lifecycle that pauses the sandbox and automatically resumes it when accessed again.
sbx = Sandbox.create(
    template="sandbox-base-node",
    timeout=-1,  # no hard lifetime; idle timeout owns reclamation
    metadata={"idleTimeout": str(idleTimeout)}, 
    lifecycle={"on_timeout": "pause", "auto_resume": True}, 
)
    
print(sbx.get_info())

# Run a background command in the sandbox
sbx.commands.run("npx serve -l 8008", background=True, timeout=0)

# Create processes snapshot for the sandbox, when the sandbox is resumed,
# the background command can be restored automatically
sbx.create_snapshot()

# Upload file to sandbox
with open("README.md", "rb") as file:
    sbx.files.write("README.md", file)

f = sbx.files.list("/home")
print(f)

You can also manage sandboxes via the built-in Web UI, accessible at http://agent-sandbox.your-host.com/ui, or continue to use the E2B SDK for programmatic control.

Why Use Agent-Sandbox?

Agent-Sandbox stands out for its simplicity, comprehensive features, and extensibility, making it an ideal choice for AI agent development:

Lightweight, Easy to Run: Deploy with a single command, kubectl apply -f install.yaml, in under a minute. It requires no external databases or message queues, leveraging native Kubernetes objects for state management. A built-in Web UI is included in the same image for easy management.
Feature-Complete for AI Sandbox Workloads: It offers full E2B protocol and SDK compatibility, covering essential AI agent needs like code execution, browser use, computer/desktop use, and shell access. Production-grade features include multi-tenant isolation, a Sandbox Pool for low-latency allocation, Pause/Resume, Snapshot capabilities, scale-to-zero on idle, leader election for high availability, and comprehensive events and metrics.
Flexible, Built to Be Extended: Agent-Sandbox provides two independent, live-editable layers, Blueprint and Template, allowing dynamic configuration of sandbox deployment and types without redeployment. It supports dynamic templates matched by regex and offers per-template resource limits, warmup commands, and pool sizing for diverse sandbox requirements.