---
title: SDK Development Guide
description: Full integration guide for SandAgent SDK
---

## Installation

```bash
npm install @sandagent/sdk ai
```

Optional sandbox providers:

```bash
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

```typescript
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

```typescript
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

| Adapter | Use Case | Package |
|---------|----------|---------|
| `LocalSandbox` | Local dev/test | Built in |
| `E2BSandbox` | Cloud production | `@sandagent/sandbox-e2b` |
| `DaytonaSandbox` | Persistent volumes | `@sandagent/sandbox-daytona` |
| `SandockSandbox` | Docker-based | `@sandagent/sandbox-sandock` |

See [Sandbox Configuration](/docs/sandboxes) and [Sandbox Reuse](/docs/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`
