🏖️ SandAgent

SDK Development Guide

Full integration guide for SandAgent SDK

Installation

npm install @sandagent/sdk ai

Optional sandbox providers:

npm install @sandagent/sandbox-e2b
npm install @sandagent/sandbox-daytona
npm install @sandagent/sandbox-sandock

Core Concepts

  • Provider: createSandAgent() returns an AI SDK-compatible model
  • Sandbox: isolates code execution (local or cloud)
  • Runner: executes the agent inside the sandbox

Minimal Setup

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

const sandbox = new LocalSandbox({
  workdir: process.cwd(),
  templatesPath: process.cwd(),
});

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

Next.js Integration

import { createSandAgent, LocalSandbox } from "@sandagent/sdk";
import {
  convertToModelMessages,
  createUIMessageStream,
  createUIMessageStreamResponse,
  streamText,
} from "ai";

export async function POST(request: Request) {
  const { messages } = await request.json();

  const sandbox = new LocalSandbox({
    workdir: process.cwd(),
    templatesPath: process.cwd(),
    runnerCommand: ["npx", "-y", "@sandagent/runner-cli@latest", "run"],
    env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  });

  const stream = createUIMessageStream({
    execute: async ({ writer }) => {
      const sandagent = createSandAgent({ sandbox, cwd: sandbox.getWorkdir() });
      const result = streamText({
        model: sandagent("sonnet"),
        messages: await convertToModelMessages(messages),
        abortSignal: request.signal,
      });
      writer.merge(result.toUIMessageStream());
    },
  });

  return createUIMessageStreamResponse({ stream });
}

Sandbox Options

AdapterUse CasePackage
LocalSandboxLocal dev/testBuilt in
E2BSandboxCloud production@sandagent/sandbox-e2b
DaytonaSandboxPersistent volumes@sandagent/sandbox-daytona
SandockSandboxDocker-based@sandagent/sandbox-sandock

See Sandbox Configuration and Sandbox Reuse for details.

Production Notes

  • Use a server sandbox provider (E2B/Daytona/Sandock)
  • Ensure provider API keys are set
  • Increase timeout for long-running tasks

Troubleshooting

  • Missing API key → verify env vars
  • Template not found → deploy or use templatesPath
  • No streaming → check AI SDK integration and createUIMessageStream

On this page