@bunny-agent/sandbox-sandock

Sandock sandbox adapter for Bunny Agent. Runs AI agents in Sandock remote sandboxes (instead of locally or via E2B/Daytona), with persistent volumes, seed-file uploads, and fast-start images.

Prerequisites

• Node.js 20+
• Sandock API Key (env: SANDOCK_API_KEY)

Install

npm install @bunny-agent/sandbox-sandock

Quick Start

import { SandockSandbox } from "@bunny-agent/sandbox-sandock";

const sandbox = new SandockSandbox({
  apiKey: process.env.SANDOCK_API_KEY,
  workdir: "/workspace",
  image: "ghcr.io/vikadata/bunny-agent:latest",
  skipBootstrap: true,
});

Key Options

Usage Patterns

1. Minimal (Pre-built Image)

new SandockSandbox({
  apiKey: process.env.SANDOCK_API_KEY,
  image: "ghcr.io/vikadata/bunny-agent:latest",
  skipBootstrap: true,
  workdir: "/workspace",
});

2. With Persistent Volumes

new SandockSandbox({
  apiKey: process.env.SANDOCK_API_KEY,
  image: "ghcr.io/vikadata/bunny-agent:latest",
  skipBootstrap: true,
  workdir: "/workspace",
  volumes: [
    { volumeName: "my-workspace", volumeMountPath: "/workspace" },
    { volumeName: "my-session", volumeMountPath: "/root/.claude" },
  ],
});

3. Reuse Existing Sandbox

Pass sandboxId to reattach to a previously created sandbox. The adapter will only reattach if the sandbox is currently in RUNNING state. If the sandbox is stopped, paused, or no longer exists, attach() falls back to creating a new one automatically.

const sandbox = new SandockSandbox({
  apiKey: process.env.SANDOCK_API_KEY,
  image: "ghcr.io/vikadata/bunny-agent:latest",
  skipBootstrap: true,
  workdir: "/workspace",
  sandboxId: "cached-sandbox-id", // from your cache
});

const handle = await sandbox.attach();
// Store handle.getSandboxId() for next request

Note: The adapter does not attempt to start a stopped sandbox. Only RUNNING sandboxes are reused. This avoids unexpected cold-start delays and ensures a consistent attach experience.

For web apps, cache the sandboxId server-side (e.g. in-memory Map with 30-min TTL) so subsequent requests reuse the same sandbox without client-side state. Use keep: true (the default) to keep sandboxes running between requests.

With @bunny-agent/sdk

import { createBunnyAgent } from "@bunny-agent/sdk";
import { SandockSandbox } from "@bunny-agent/sandbox-sandock";
import { generateText } from "ai";

const bunnyAgent = createBunnyAgent({
  sandbox: new SandockSandbox({
    apiKey: process.env.SANDOCK_API_KEY,
    workdir: "/workspace",
    image: "ghcr.io/vikadata/bunny-agent:latest",
    skipBootstrap: true,
  }),
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const { text } = await generateText({
  model: bunnyAgent("sonnet"),
  prompt: "Create a hello world program",
});

Install: npm install @bunny-agent/sandbox-sandock @bunny-agent/sdk ai

API

SandockSandbox (Adapter)

• attach() — Create or reuse a sandbox; returns a SandboxHandle
• getHandle() — Returns the current handle if attached, otherwise null

SandboxHandle (returned by attach())

• getSandboxId() — Returns the sandbox instance ID
• getVolumes() — Returns mounted volume list (or null)
• getWorkdir() — Returns the working directory
• exec(command, opts) — Execute a command and stream output
• upload(files, targetDir) — Upload files to the sandbox
• readFile(filePath) — Read a file from the sandbox
• destroy() — Stop and delete the sandbox

About skipBootstrap

• skipBootstrap: true: Image already includes bunny-agent run; only upload seed files (from templatesPath), no runner install. Use with pre-built images like ghcr.io/vikadata/bunny-agent:latest.
• skipBootstrap: false: On attach, runs npm install @bunny-agent/runner-cli@latest in workdir, then uses ${workdir}/node_modules/.bin/bunny-agent run for execution.

License

Apache-2.0