Agent Sandbox

Agent Sandbox gives AI agents an isolated sandbox backed by Docker — somewhere to run code, install packages, execute commands, and manage files without touching your machine.

Features

• Isolated by default — each sandbox is a Docker container, fully separated from the host
• Persistent storage — every sandbox gets a dedicated /data volume that survives across commands
• Self-hosted — runs on your own machine via Docker, no cloud or API keys required

Primitives

create  delete  list  read  write  upload  download

Interfaces

Package	Role
@agent-sandbox/cli	Human-facing command line wrapper over the core primitives
@agent-sandbox/mcp	MCP server that exposes the primitives as tools
@agent-sandbox/api	Small programmatic wrapper for app/server integration

Quick Start

CLI

# install or upgrade
npm install -g @agent-sandbox/cli

agent-sandbox create
agent-sandbox list

MCP

{
  "mcpServers": {
    "agent-sandbox": {
      "command": "npx",
      "args": ["-y", "@agent-sandbox/mcp"]
    }
  }
}

API

npm install @agent-sandbox/api

import { AgentSandbox } from "@agent-sandbox/api";

const sandbox = new AgentSandbox();
const created = await sandbox.create();

await sandbox.write({
  sandboxId: created.sandboxId,
  input: "printf 'hello\\n' > /proc/1/fd/1",
});

console.log(
  (
    await sandbox.read({
      sandboxId: created.sandboxId,
    })
  ).output,
);

await sandbox.delete({
  sandboxId: created.sandboxId,
});

Documentation

Use the package READMEs for package-specific usage and reference:

• CLI package docs
• MCP package docs
• API package docs

Skill

npx skills add https://github.com/usamaasfar/agent-sandbox/tree/main/skills/agent-sandbox-cli

License

MIT