# Sandbox reference

Anthropic code execution, container reuse, and sandbox file helpers.

```ts
import {
  codeExecutionTool, callableFromSandbox,
  forwardSandboxContainer, reuseSandbox,
  sandboxUpload, sandboxOutputs, sandboxFiles, SandboxFileError,
} from 'deepspace/worker'
import type {
  DeepSpaceAIEnv, SandboxScope, SandboxFile, SandboxFileList,
  SandboxFilesClient, SandboxFilesOptions, SandboxUploadOptions,
} from 'deepspace/worker'
```

These helpers use Anthropic's hosted sandbox through the DeepSpace proxy. See the [sandbox guide](/guides/anthropic-sandbox) for the upload, run, and download sequence.

## Code execution

| Helper                      | Use                                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `codeExecutionTool()`       | Add to `tools` as `code_execution`. Claude starts a container when it uses the tool.                                |
| `callableFromSandbox(tool)` | Returns a copy of an AI tool that Claude can call directly or from sandbox code. Execution stays in your Worker.    |
| `forwardSandboxContainer`   | Pass as `prepareStep` to keep the same container across steps in a turn.                                            |
| `reuseSandbox(containerId)` | Pass as `providerOptions` to continue in a saved container. Returns `undefined` for a missing ID.                   |
| `sandboxUpload(file)`       | Builds a message `FilePart` that copies an uploaded file into the container. Accepts `{ id, filename, mime_type }`. |
| `sandboxOutputs(steps)`     | Reads completed steps and returns `{ containerId: string \| null, fileIds: string[] }`. File IDs are deduplicated.  |

Use `streamText` from `ai` and drain the stream before reading outputs. For saved containers, the caller must have access under the scope used when the container was created.

## `sandboxFiles(env, options?)`

Returns a client for the calling app's sandbox files.

```ts
function sandboxFiles(
  env: DeepSpaceAIEnv,
  options?: SandboxFilesOptions,
): SandboxFilesClient

interface SandboxFilesOptions {
  authToken?: string
  scope?: 'user' | 'app'
}
```

| Option      | Effect                                                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| `authToken` | Verified caller's JWT. Omit to use `env.APP_OWNER_JWT`.                                                                 |
| `scope`     | Scope for new uploads. Defaults to `'user'`; `'app'` shares within the app. Match `createDeepSpaceAI`'s `sandboxScope`. |

The Worker needs `DEEPSPACE_APP_ID` and `APP_IDENTITY_TOKEN` in `env`. DeepSpace supplies the token at deploy time. Redeploy after upgrading if the app predates sandbox support.

### `upload(file, options?)`

```ts
upload(file: Blob, options?: SandboxUploadOptions): Promise<SandboxFile>

interface SandboxUploadOptions {
  filename?: string
  expiresInSeconds?: number
}
```

Pass a `File`, or a `Blob` with `options.filename`. Maximum size: 32 MiB. `expiresInSeconds` defaults to 2,592,000 (30 days) and accepts integers from 3,600 to 7,776,000 (one hour to 90 days).

### `get(fileId)` / `download(fileId)`

```ts
get(fileId: string): Promise<SandboxFile>
download(fileId: string): Promise<Response>
```

`get` returns metadata. `download` returns the bytes as a streaming response with `content-type` and `content-disposition` headers. Downloads are available for sandbox-created files, not uploads.

### `list(options?)`

```ts
list(options?: { limit?: number; page?: string }): Promise<SandboxFileList>

interface SandboxFileList {
  data: SandboxFile[]
  next_page: string | null
}
```

Lists files visible to the caller in this app. `limit` defaults to 20 and accepts 1–100. Pass the returned `next_page` as `page` until it is `null`.

### `delete(fileId)`

```ts
delete(fileId: string): Promise<void>
```

Deletes a file the caller can access. Sandbox-created files do not automatically expire; delete them after storing any outputs your app needs.

## `SandboxFile`

```ts
interface SandboxFile {
  type: 'file'
  id: string
  filename: string
  mime_type: string
  size_bytes: number
  created_at: string
  downloadable?: boolean
  expires_at?: string | null
}
```

## Errors

File requests throw `SandboxFileError`, an `Error` with a numeric `status`. An ID outside the caller's app or user scope returns 404, just like an unknown ID. Oversized uploads return 413.

## See also

* [Sandbox guide](/guides/anthropic-sandbox) - document editing and file scope.
* [AI reference](/sdk-reference/worker/ai) - `createDeepSpaceAI` and `sandboxScope`.
* [Rooms reference](/sdk-reference/worker/rooms#jobroom-e) - long-running job configuration.