Sandboxes

Execution environments for bashkit tools. Choose the right sandbox for your use case.

Sandbox Interface

All sandboxes implement the same interface. Tools depend on this abstraction, not specific implementations — so you can swap sandboxes without changing tool code.

interface Sandbox {
  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  readDir(path: string): Promise<string[]>;
  fileExists(path: string): Promise<boolean>;
  isDirectory(path: string): Promise<boolean>;
  destroy(): Promise<void>;
  readonly id?: string;  // For reconnection (cloud only)
  rgPath?: string;       // Path to ripgrep binary
}

LocalSandbox

Uses Bun/Node APIs directly. The fastest option with zero network overhead. Best for development and local testing.

import { createLocalSandbox } from 'bashkit';

const sandbox = createLocalSandbox({
  workingDirectory: '/path/to/project',
});

// No extra dependencies needed
// Fastest execution — direct system calls
// No isolation — runs on your machine

No extra dependencies — works out of the box
Fastest execution — direct Bun/Node API calls
No isolation — commands run on your machine
Best for — development, local testing, CI/CD

VercelSandbox

Runs in Vercel's Firecracker micro-VMs. Provides full isolation with fast boot times. Requires the @vercel/sandbox package.

import { createVercelSandbox, createAgentTools } from 'bashkit';

// Async — auto-sets up ripgrep
const sandbox = await createVercelSandbox();

const { tools } = await createAgentTools(sandbox);
// Grep tool works immediately — rgPath is pre-configured

// Clean up when done
await sandbox.destroy();

npm install @vercel/sandbox

Full isolation — Firecracker micro-VMs
Fast boot — sub-second startup
Auto-setup — ripgrep installed automatically
Best for — production deployments, untrusted code execution

E2BSandbox

Runs on E2B's hosted infrastructure. Good for serverless environments where you can't run local processes. Requires the @e2b/code-interpreter package and an E2B API key.

import { createE2BSandbox, createAgentTools } from 'bashkit';

// Async — auto-sets up ripgrep
const sandbox = await createE2BSandbox({
  apiKey: process.env.E2B_API_KEY,
});

const { tools } = await createAgentTools(sandbox);

// Reconnect to an existing sandbox
const reconnected = await createE2BSandbox({
  apiKey: process.env.E2B_API_KEY,
  sandboxId: sandbox.id,
});

await sandbox.destroy();

npm install @e2b/code-interpreter

Hosted execution — no local processes needed
Reconnectable — resume sandboxes by ID
Auto-setup — ripgrep installed automatically
Best for — serverless, hosted applications