Sandbox Configuration

SandAgent runs Coding Agents inside sandboxes — isolated environments with their own filesystem. You choose between local execution and cloud sandboxes depending on your use case.

Local Sandbox

Built-in, no extra packages. The agent runs directly on your machine's filesystem.

import { createSandAgent, LocalSandbox } from "@sandagent/sdk";

const sandbox = new LocalSandbox({
  workdir: "/path/to/project",
  templatesPath: "./my-agent-template",
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const sandagent = createSandAgent({ sandbox, cwd: sandbox.getWorkdir() });

Best for: Electron/Tauri desktop apps, local development, debugging.

Option	Description
`workdir`	Working directory for the agent
`templatesPath`	Path to agent template directory (copied into workdir)
`runnerCommand`	Custom runner command (defaults to built-in)
`env`	Environment variables passed to the agent

Sandock (Recommended for Cloud)

Sandock provides Docker-based cloud sandboxes with persistent volumes and fast startup.

Why Sandock? Coding Agents (Claude Code, Codex CLI, etc.) rely heavily on filesystem append operations and other POSIX semantics during execution. Sandock is currently the only cloud sandbox provider that offers 100% POSIX-compatible filesystems, ensuring Coding Agents run without filesystem-related failures. Additionally, Sandock volumes are persistent and shareable — multiple sandboxes can mount the same named volume, enabling cross-session and cross-sandbox data reuse.

Install

npm install @sandagent/sandbox-sandock

Get an API Key

Go to sandock.ai
Sign up and create an API key
Set SANDOCK_API_KEY in your environment

Usage

import { createSandAgent } from "@sandagent/sdk";
import { SandockSandbox } from "@sandagent/sandbox-sandock";

const sandbox = new SandockSandbox({
  apiKey: process.env.SANDOCK_API_KEY,
  image: "vikadata/sandagent:0.1.0",  // Pre-built image (fast startup)
  skipBootstrap: true,
  workdir: "/workspace",
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const sandagent = createSandAgent({ sandbox, cwd: sandbox.getWorkdir() });

Volumes persist across sandbox restarts and can be shared across multiple sandboxes. This means different agent sessions can access the same workspace data, and Claude's session history (stored in /root/.claude) survives sandbox recreation.

const sandbox = new SandockSandbox({
  apiKey: process.env.SANDOCK_API_KEY,
  image: "vikadata/sandagent:0.1.0",
  skipBootstrap: true,
  workdir: "/workspace",
  volumes: [
    { volumeName: "my-workspace", volumeMountPath: "/workspace" },
    { volumeName: "my-claude-session", volumeMountPath: "/root/.claude" },
  ],
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

Options

Option	Default	Description
`apiKey`	`SANDOCK_API_KEY` env	Sandock API key
`baseUrl`	`https://sandock.ai`	Sandock API endpoint
`image`	`sandockai/sandock-code:latest`	Docker image. Use `vikadata/sandagent:0.1.0` for pre-built
`skipBootstrap`	`false`	`true` when using pre-built image (skips npm install inside sandbox)
`workdir`	`/workspace`	Working directory inside sandbox
`volumes`	`[]`	Named volumes for persistent storage
`keep`	`true`	Keep sandbox alive ~30 min after execution
`memoryLimitMb`	—	Memory limit in MB
`cpuShares`	—	CPU shares
`timeout`	`300000`	Command timeout in ms (5 min)
`templatesPath`	—	Local template directory to upload into sandbox
`name`	—	Sandbox name for identification

Bootstrap Modes

Pre-built image (skipBootstrap: true): Uses sandagent run from the image. Fastest startup.

new SandockSandbox({
  image: "vikadata/sandagent:0.1.0",
  skipBootstrap: true,
});

Dynamic install (skipBootstrap: false): Installs @sandagent/runner-cli@latest via npm inside the sandbox. More flexible, slower startup.

new SandockSandbox({
  image: "sandockai/sandock-code:latest",
  skipBootstrap: false,
});

E2B

E2B provides cloud sandboxes optimized for AI agents.

npm install @sandagent/sandbox-e2b

import { E2BSandbox } from "@sandagent/sandbox-e2b";

const sandbox = new E2BSandbox({
  apiKey: process.env.E2B_API_KEY,
});

Daytona

Daytona provides enterprise workspace environments.

npm install @sandagent/sandbox-daytona

import { DaytonaSandbox } from "@sandagent/sandbox-daytona";

const sandbox = new DaytonaSandbox({
  apiKey: process.env.DAYTONA_API_KEY,
});

Comparison

Provider	Best For	POSIX FS	Pre-built Images	Network Limits	Volume Reuse Across Sandboxes	Volume Public Access
LocalSandbox	Desktop apps, debugging	✅ (native)	N/A	None	N/A	N/A
Sandock	Cloud production	✅ Full POSIX	✅	None	✅	✅
E2B	Cloud production	✅	✅	None	❌	❌
Daytona	Cloud production	❌	✅	Tier 1 & 2	✅	❌
Sandock	Cloud production	✅ Full POSIX	✅ Cross-sandbox	✅
E2B	Cloud production	⚠️ Partial	❌	✅
Daytona	Enterprise workspaces	⚠️ Partial	❌	✅

af04389 (Update documentation)