agentbox-sdk 0.0.0 → 0.1.0

package/README.md

@@ -0,0 +1,399 @@
+# AgentBox
+
+Run coding agents inside sandboxes. One API, any provider.
+
+Unlike wrappers that shell out to CLIs in non-interactive mode (e.g. `claude --print`), AgentBox launches each agent as a **server process** inside the sandbox and communicates over WebSocket or HTTP. This preserves the full interactive capabilities of each agent — approval flows, tool-use control, streaming events.
+
+```ts
+import { Agent, Sandbox } from "agentbox-sdk";
+
+const sandbox = new Sandbox("local-docker", {
+  workingDir: "/workspace",
+  image: process.env.IMAGE_ID!,
+  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
+});
+
+const run = new Agent("claude-code", {
+  sandbox,
+  cwd: "/workspace",
+  approvalMode: "auto",
+}).stream({
+  model: "claude-sonnet-4-6",
+  input: "Create a hello world Express server in /workspace/server.ts",
+});
+
+for await (const event of run) {
+  if (event.type === "text.delta") process.stdout.write(event.delta);
+}
+
+await sandbox.delete();
+```
+
+Providers are mix-and-match:
+
+- **Agents** — [`claude-code`](./src/agents/providers/claude-code.ts), [`opencode`](./src/agents/providers/opencode.ts), [`codex`](./src/agents/providers/codex.ts)
+- **Sandboxes** — [`local-docker`](./src/sandboxes/providers/local-docker.ts), [`e2b`](./src/sandboxes/providers/e2b.ts), [`modal`](./src/sandboxes/providers/modal.ts), [`daytona`](./src/sandboxes/providers/daytona.ts)
+
+Swap either one and your app code stays the same.
+
+## Install
+
+```bash
+npm install agentbox-sdk
+```
+
+Requires Node >= 20. The agent CLI you want to use (`claude`, `opencode`, `codex`) should be installed inside your sandbox image.
+
+## Getting started
+
+### 1. Build a sandbox image
+
+AgentBox ships with built-in image presets. Build one for your sandbox provider:
+
+```bash
+npx agentbox image build --provider local-docker --preset browser-agent
+```
+
+This prints an image reference (a Docker tag, Modal image ID, E2B template, or Daytona snapshot depending on the provider). Set it as `IMAGE_ID`:
+
+```bash
+export IMAGE_ID=<printed value>
+```
+
+### 2. Run an agent
+
+```ts
+import { Agent, Sandbox } from "agentbox-sdk";
+
+const sandbox = new Sandbox("local-docker", {
+  workingDir: "/workspace",
+  image: process.env.IMAGE_ID!,
+  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
+});
+
+const agent = new Agent("claude-code", {
+  sandbox,
+  cwd: "/workspace",
+  approvalMode: "auto",
+});
+
+const result = await agent.run({
+  model: "claude-sonnet-4-6",
+  input:
+    "Explain the project structure and write a summary to /workspace/OVERVIEW.md",
+});
+
+console.log(result.text);
+await sandbox.delete();
+```
+
+### 3. Stream events
+
+`agent.stream()` returns an async iterable of normalized events:
+
+```ts
+const run = agent.stream({
+  model: "claude-sonnet-4-6",
+  input: "Write a fizzbuzz in Python",
+});
+
+for await (const event of run) {
+  if (event.type === "text.delta") {
+    process.stdout.write(event.delta);
+  }
+}
+
+const result = await run.finished;
+```
+
+## Agents
+
+Three agent providers are supported. Each wraps a CLI that runs inside the sandbox:
+
+| Provider      | CLI        | Model format                                    |
+| ------------- | ---------- | ----------------------------------------------- |
+| `claude-code` | `claude`   | `claude-sonnet-4-6`                             |
+| `opencode`    | `opencode` | `anthropic/claude-sonnet-4-6`, `openai/gpt-4.1` |
+| `codex`       | `codex`    | `gpt-5-codex`                                   |
+
+```ts
+new Agent("claude-code", { sandbox, cwd: "/workspace", approvalMode: "auto" });
+new Agent("opencode", { sandbox, cwd: "/workspace", approvalMode: "auto" });
+new Agent("codex", { sandbox, cwd: "/workspace", approvalMode: "auto" });
+```
+
+## Sandboxes
+
+Four sandbox providers are supported. Each gives you an isolated environment with the same interface:
+
+| Provider       | What it is             | Auth                                    |
+| -------------- | ---------------------- | --------------------------------------- |
+| `local-docker` | Local Docker container | Docker daemon                           |
+| `e2b`          | Cloud micro-VM         | `E2B_API_KEY`                           |
+| `modal`        | Cloud container        | `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET` |
+| `daytona`      | Cloud dev environment  | `DAYTONA_API_KEY`                       |
+
+Every sandbox supports: `run()`, `runAsync()`, `gitClone()`, `openPort()`, `getPreviewLink()`, `snapshot()`, `stop()`, `delete()`.
+
+## Skills
+
+Attach GitHub repos as agent skills. They're cloned into the sandbox and surfaced to the agent:
+
+```ts
+const agent = new Agent("claude-code", {
+  sandbox,
+  cwd: "/workspace",
+  approvalMode: "auto",
+  skills: [
+    {
+      name: "agent-browser",
+      repo: "https://github.com/vercel-labs/agent-browser",
+    },
+  ],
+});
+```
+
+You can also embed skills inline:
+
+```ts
+skills: [
+  {
+    source: "embedded",
+    name: "lint-fix",
+    files: {
+      "SKILL.md": "Run `npm run lint:fix` and verify the output is clean.",
+    },
+  },
+],
+```
+
+## Sub-agents
+
+Delegate tasks to specialized sub-agents:
+
+```ts
+const agent = new Agent("claude-code", {
+  sandbox,
+  cwd: "/workspace",
+  approvalMode: "auto",
+  subAgents: [
+    {
+      name: "reviewer",
+      description: "Reviews code for bugs and security issues",
+      instructions:
+        "Flag bugs, security issues, and missing edge cases. Be concise.",
+      tools: ["bash", "read"],
+    },
+  ],
+});
+```
+
+## MCP servers
+
+Connect MCP servers to give agents access to external tools:
+
+```ts
+const agent = new Agent("claude-code", {
+  sandbox,
+  cwd: "/workspace",
+  approvalMode: "auto",
+  mcps: [
+    {
+      name: "filesystem",
+      type: "local",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
+    },
+    {
+      name: "my-api",
+      type: "remote",
+      url: "https://mcp.example.com/sse",
+    },
+  ],
+});
+```
+
+## Custom commands
+
+Register slash commands the agent can use:
+
+```ts
+const agent = new Agent("opencode", {
+  sandbox,
+  cwd: "/workspace",
+  approvalMode: "auto",
+  commands: [
+    {
+      name: "triage",
+      description: "Triage a bug report into root cause + fix plan",
+      template:
+        "Analyze the bug report. Return: root cause, files to change, and tests to add.",
+    },
+  ],
+});
+```
+
+## Multimodal input
+
+Pass images and files alongside text:
+
+```ts
+import { pathToFileURL } from "node:url";
+
+const result = await agent.run({
+  model: "claude-sonnet-4-6",
+  input: [
+    { type: "text", text: "Describe this mockup and suggest improvements." },
+    { type: "image", image: pathToFileURL("/workspace/mockup.png") },
+  ],
+});
+```
+
+Provider support: `opencode` (text, images, files), `claude-code` (text, images, PDFs), `codex` (text, images).
+
+## Custom sandbox images
+
+Define your own image when the built-in presets don't cover your needs.
+
+Create `my-image.mjs`:
+
+```js
+export default {
+  name: "playwright-sandbox",
+  base: "node:20-bookworm",
+  env: { PLAYWRIGHT_BROWSERS_PATH: "/ms-playwright" },
+  run: [
+    "apt-get update && apt-get install -y git python3 ca-certificates",
+    "npm install -g pnpm @anthropic-ai/claude-code",
+    "npx playwright install --with-deps chromium",
+  ],
+  workdir: "/workspace",
+  cmd: ["sleep", "infinity"],
+};
+```
+
+Build it:
+
+```bash
+npx agentbox image build --provider local-docker --file ./my-image.mjs
+```
+
+This works with all providers. For cloud providers, the printed value will be that provider's native image reference.
+
+## Hooks
+
+Hooks let you run code at specific points in the agent lifecycle. Each provider has its own hook format:
+
+**Claude Code** — native hook settings:
+
+```ts
+new Agent("claude-code", {
+  sandbox,
+  cwd: "/workspace",
+  provider: {
+    hooks: {
+      PostToolUse: [
+        { matcher: "Bash", hooks: [{ type: "command", command: "echo done" }] },
+      ],
+    },
+  },
+});
+```
+
+**Codex** — similar to Claude Code:
+
+```ts
+new Agent("codex", {
+  sandbox,
+  cwd: "/workspace",
+  provider: {
+    hooks: {
+      PostToolUse: [
+        { matcher: "Bash", hooks: [{ type: "command", command: "echo done" }] },
+      ],
+    },
+  },
+});
+```
+
+**OpenCode** — plugin-based hooks:
+
+```ts
+new Agent("opencode", {
+  sandbox,
+  cwd: "/workspace",
+  provider: {
+    plugins: [
+      {
+        name: "session-notifier",
+        hooks: [{ event: "session.idle", body: 'return "session-idle";' }],
+      },
+    ],
+  },
+});
+```
+
+## Examples
+
+The [`examples/`](./examples) directory has short, runnable scripts that each demonstrate one feature:
+
+| Example                                                         | What it shows                 |
+| --------------------------------------------------------------- | ----------------------------- |
+| [`basic.ts`](./examples/basic.ts)                               | Minimal agent + sandbox       |
+| [`streaming.ts`](./examples/streaming.ts)                       | Stream and handle events      |
+| [`interactive-approval.ts`](./examples/interactive-approval.ts) | Approve tool calls from stdin |
+| [`skills.ts`](./examples/skills.ts)                             | Attach a GitHub skill         |
+| [`sub-agents.ts`](./examples/sub-agents.ts)                     | Delegate to sub-agents        |
+| [`mcp-server.ts`](./examples/mcp-server.ts)                     | Connect an MCP server         |
+| [`multimodal.ts`](./examples/multimodal.ts)                     | Send images to the agent      |
+| [`custom-image.ts`](./examples/custom-image.ts)                 | Build a custom sandbox image  |
+| [`cloud-sandbox.ts`](./examples/cloud-sandbox.ts)               | Use E2B, Modal, or Daytona    |
+| [`git-clone.ts`](./examples/git-clone.ts)                       | Clone a repo into the sandbox |
+
+All examples import from `"agentbox-sdk"` like a normal dependency. Run them with:
+
+```bash
+npx tsx examples/basic.ts
+```
+
+## Package exports
+
+```ts
+import { Agent, Sandbox } from "agentbox-sdk"; // main entrypoint
+import type { AgentRun } from "agentbox-sdk/agents"; // agent types
+import type { CommandResult } from "agentbox-sdk/sandboxes"; // sandbox types
+import type { NormalizedAgentEvent } from "agentbox-sdk/events"; // event types
+```
+
+## Contributing
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm test
+```
+
+`npm run build` generates the `dist/` directory. You need to build before the examples or CLI work locally.
+
+To test your local build from another project:
+
+```bash
+npm run build && npm pack
+# then in your project:
+npm install /path/to/agentbox-sdk-0.1.0.tgz
+```
+
+### Tests
+
+```bash
+npm test                                              # fast, no real providers
+AGENTBOX_RUN_SMOKE_TESTS=1 npm run test:smoke         # live smoke tests
+AGENTBOX_RUN_MATRIX_E2E=1 npm run test:e2e:matrix     # provider matrix
+```
+
+Live test suites are opt-in because they provision real infrastructure.
+
+## License
+
+MIT

package/dist/Sandbox-DTprxRZf.d.ts

@@ -0,0 +1,182 @@
+import { Sandbox as Sandbox$1 } from 'e2b';
+import { Daytona, Sandbox as Sandbox$2 } from '@daytonaio/sdk';
+import { ModalClient, Sandbox as Sandbox$3 } from 'modal';
+import Docker from 'dockerode';
+
+type E2bRaw = {
+    sandbox?: Sandbox$1;
+};
+
+type DaytonaRaw = {
+    client: Daytona;
+    sandbox?: Sandbox$2;
+};
+
+type ModalRaw = {
+    client: ModalClient;
+    sandbox?: Sandbox$3;
+};
+
+type DockerRaw = {
+    client: Docker;
+    container?: Docker.Container;
+};
+
+type SandboxProviderName = "local-docker" | "modal" | "daytona" | "e2b";
+interface CommandOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    pty?: boolean;
+}
+interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    combinedOutput: string;
+    raw?: unknown;
+}
+interface CommandEvent {
+    type: "stdout" | "stderr" | "exit";
+    chunk?: string;
+    exitCode?: number;
+    timestamp: string;
+    raw?: unknown;
+}
+interface AsyncCommandHandle extends AsyncIterable<CommandEvent> {
+    id: string;
+    raw?: unknown;
+    write?(input: string): Promise<void>;
+    wait(): Promise<CommandResult>;
+    kill(): Promise<void>;
+}
+interface GitCloneOptions {
+    repoUrl: string;
+    branch?: string;
+    targetDir?: string;
+    depth?: number;
+    token?: string;
+    headers?: Record<string, string>;
+}
+interface SandboxListOptions {
+    tags?: Record<string, string>;
+}
+interface SandboxDescriptor {
+    provider: SandboxProviderName;
+    id: string;
+    state?: string;
+    tags: Record<string, string>;
+    createdAt?: string;
+    raw?: unknown;
+}
+interface SandboxOptionsBase {
+    tags?: Record<string, string>;
+    env?: Record<string, string>;
+    workingDir?: string;
+    idleTimeoutMs?: number;
+    autoStopMs?: number;
+    image?: string;
+    resources?: SandboxResourceSpec;
+}
+interface SandboxResourceSpec {
+    cpu?: number;
+    memoryMiB?: number;
+}
+interface LocalDockerProviderOptions {
+    name?: string;
+    command?: string[];
+    pull?: boolean;
+    autoRemove?: boolean;
+    binds?: string[];
+    networkMode?: string;
+    publishedPorts?: number[];
+}
+interface ModalProviderOptions {
+    appName?: string;
+    environment?: string;
+    endpoint?: string;
+    tokenId?: string;
+    tokenSecret?: string;
+    encryptedPorts?: number[];
+    unencryptedPorts?: number[];
+    command?: string[];
+    verbose?: boolean;
+}
+interface DaytonaProviderOptions {
+    apiKey?: string;
+    jwtToken?: string;
+    organizationId?: string;
+    apiUrl?: string;
+    target?: string;
+    name?: string;
+    language?: string;
+    user?: string;
+    public?: boolean;
+}
+interface E2bProviderOptions {
+    apiKey?: string;
+    accessToken?: string;
+    domain?: string;
+    apiUrl?: string;
+    sandboxUrl?: string;
+    debug?: boolean;
+    requestTimeoutMs?: number;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    lifecycle?: {
+        onTimeout?: "pause" | "kill";
+        autoResume?: boolean;
+    };
+    secure?: boolean;
+    allowInternetAccess?: boolean;
+}
+interface LocalDockerSandboxOptions extends SandboxOptionsBase {
+    provider?: LocalDockerProviderOptions;
+}
+interface ModalSandboxOptions extends SandboxOptionsBase {
+    provider?: ModalProviderOptions;
+}
+interface DaytonaSandboxOptions extends SandboxOptionsBase {
+    provider?: DaytonaProviderOptions;
+}
+interface E2bSandboxOptions extends SandboxOptionsBase {
+    provider?: E2bProviderOptions;
+}
+type SandboxOptionsMap = {
+    "local-docker": LocalDockerSandboxOptions;
+    modal: ModalSandboxOptions;
+    daytona: DaytonaSandboxOptions;
+    e2b: E2bSandboxOptions;
+};
+type SandboxOptions<P extends SandboxProviderName = SandboxProviderName> = SandboxOptionsMap[P];
+type SandboxRawMap = {
+    "local-docker": DockerRaw;
+    modal: ModalRaw;
+    daytona: DaytonaRaw;
+    e2b: E2bRaw;
+};
+type SandboxRaw<P extends SandboxProviderName = SandboxProviderName> = SandboxRawMap[P];
+
+declare class Sandbox<P extends SandboxProviderName = SandboxProviderName> {
+    private readonly providerName;
+    private readonly options;
+    private readonly adapter;
+    constructor(providerName: P, options: SandboxOptions<P>);
+    get provider(): P;
+    get optionsSnapshot(): SandboxOptions<P>;
+    get id(): string | undefined;
+    get raw(): SandboxRaw<P> | undefined;
+    openPort(port: number): Promise<this>;
+    setSecret(name: string, value: string): this;
+    setSecrets(values: Record<string, string>): this;
+    gitClone(options: GitCloneOptions): Promise<CommandResult>;
+    run(command: string | string[], options?: CommandOptions): Promise<CommandResult>;
+    runAsync(command: string | string[], options?: CommandOptions): Promise<AsyncCommandHandle>;
+    list(options?: SandboxListOptions): Promise<SandboxDescriptor[]>;
+    snapshot(): Promise<string | null>;
+    stop(): Promise<void>;
+    delete(): Promise<void>;
+    getPreviewLink(port: number): Promise<string>;
+}
+
+export { type AsyncCommandHandle as A, type CommandEvent as C, type DaytonaProviderOptions as D, type E2bProviderOptions as E, type GitCloneOptions as G, type LocalDockerProviderOptions as L, type ModalProviderOptions as M, Sandbox as S, type CommandOptions as a, type CommandResult as b, type DaytonaSandboxOptions as c, type E2bSandboxOptions as d, type LocalDockerSandboxOptions as e, type ModalSandboxOptions as f, type SandboxDescriptor as g, type SandboxListOptions as h, type SandboxOptions as i, type SandboxOptionsBase as j, type SandboxOptionsMap as k, type SandboxProviderName as l, type SandboxRaw as m, type SandboxRawMap as n, type SandboxResourceSpec as o };

package/dist/agents/index.d.ts

@@ -0,0 +1,19 @@
+import { m as AgentProviderName, f as AgentOptions, q as AgentRunConfig, p as AgentRun, o as AgentResult, Z as RawAgentEvent } from '../types-BwcoN0n-.js';
+export { a as AgentApprovalMode, b as AgentCommandConfig, c as AgentExecutionRequest, d as AgentLocalMcpConfig, e as AgentMcpConfig, g as AgentOptionsBase, h as AgentOptionsMap, i as AgentPermissionDecision, j as AgentPermissionKind, k as AgentPermissionResponse, l as AgentProviderAdapter, n as AgentRemoteMcpConfig, r as AgentRunSink, s as AgentSkillConfig, t as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, u as ClaudeCodeHookConfig, v as ClaudeCodeHookEvent, w as ClaudeCodeHookHandler, x as ClaudeCodeHookMatcherGroup, y as ClaudeCodeHooksConfig, z as ClaudeCodeProviderOptions, B as CodexAgentOptions, D as CodexCommandHook, E as CodexHookEvent, F as CodexHookMatcherGroup, G as CodexHooksConfig, H as CodexProviderOptions, I as DataContent, J as EmbeddedSkillConfig, K as FilePart, L as ImagePart, S as OpenCodeAgentOptions, T as OpenCodePluginConfig, U as OpenCodePluginEvent, V as OpenCodePluginHookConfig, W as OpenCodeProviderOptions, $ as RepoSkillConfig, a4 as TextPart, a8 as UserContent, a9 as UserContentPart } from '../types-BwcoN0n-.js';
+import '../Sandbox-DTprxRZf.js';
+import 'e2b';
+import '@daytonaio/sdk';
+import 'modal';
+import 'dockerode';
+
+declare class Agent<P extends AgentProviderName = AgentProviderName> {
+    private readonly adapter;
+    private readonly provider;
+    private readonly options;
+    constructor(provider: P, options: AgentOptions<P>);
+    stream(runConfig: AgentRunConfig): AgentRun;
+    run(runConfig: AgentRunConfig): Promise<AgentResult>;
+    rawEvents(runConfig: AgentRunConfig): AsyncIterable<RawAgentEvent>;
+}
+
+export { Agent, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig };

package/dist/agents/index.js

@@ -0,0 +1,9 @@
+import {
+  Agent
+} from "../chunk-BW43ESRM.js";
+import "../chunk-7FLLQJ6J.js";
+import "../chunk-HMBWQSVN.js";
+import "../chunk-JFDP556Q.js";
+export {
+  Agent
+};