> ## Documentation Index
> Fetch the complete documentation index at: https://docs.podflare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> import { Sandbox } from 'podflare'

## Install

```bash theme={null}
npm install podflare
```

ESM only, Node 20+.

## Configuration

```ts theme={null}
import { Sandbox, Client } from "podflare";

// Default: reads PODFLARE_HOSTD_URL env var, falls back to https://api.podflare.ai
const sbx = await Sandbox.create();

// Explicit host
const sbx = await Sandbox.create({ host: "https://api.podflare.ai" });

// Shared Client for many sandboxes
const client = new Client({ host: "https://api.podflare.ai" });
const a = await Sandbox.create({ client });
const b = await Sandbox.create({ client });
```

## Core verbs

### `runCode(code, language?): Promise<ExecResult>`

```ts theme={null}
const r = await sbx.runCode("print(sum(range(10)))");
console.log(r.stdout, r.exitCode);
```

### `runCodeStream(code, language?): AsyncGenerator<Event>`

```ts theme={null}
for await (const ev of sbx.runCodeStream("for i in range(3): print(i)")) {
  if (ev.type === "stdout") process.stdout.write(ev.data + "\n");
}
```

### `fork(n=1): Promise<Sandbox[]>`

See [Fork](/concepts/fork) for semantics.

```ts theme={null}
const children = await parent.fork(5);
```

### `diff(other, paths?): Promise<{added, removed, modified}>`

```ts theme={null}
const d = await a.diff(b);
```

### `mergeInto(winner): Promise<void>`

```ts theme={null}
await parent.mergeInto(winner);
```

### `upload(data, remotePath) / download(remotePath)`

```ts theme={null}
await sbx.upload(new TextEncoder().encode("hello"), "/root/hello.txt");
const bytes = await sbx.download("/root/hello.txt");
console.log(new TextDecoder().decode(bytes));
```

### `close(): Promise<void>`

```ts theme={null}
const sbx = await Sandbox.create();
try {
  // ...
} finally {
  await sbx.close();
}
```

## Vercel AI SDK adapter

Subpath import: `"podflare/ai-sdk"`.

```ts theme={null}
import { tool } from "ai";
import { z } from "zod";
import { podflareRunCode } from "podflare/ai-sdk";

const pf = podflareRunCode();

const { text } = await generateText({
  model: anthropic("claude-opus-4-7"),
  tools: {
    runCode: tool({
      description: pf.description,
      parameters: z.object({
        code: z.string(),
        language: z.enum(["python", "bash"]).optional(),
      }),
      execute: pf.execute,
    }),
  },
  prompt: "Use runCode to compute sqrt(12345)",
});

await pf.close();
```

See [Vercel AI SDK](/integrations/vercel-ai-sdk) for the full guide.

## Types

```ts theme={null}
import type { Sandbox, Event, ExecResult, Language } from "podflare";
```