Skip to main content
Documentation
SDK reference

Sandbox reference

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

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

These helpers use Anthropic's hosted sandbox through the DeepSpace proxy. See the sandbox guide for the upload, run, and download sequence.

Code execution#

HelperUse
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.
forwardSandboxContainerPass 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.

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

interface SandboxFilesOptions {
  authToken?: string
  scope?: 'user' | 'app'
}
ts
OptionEffect
authTokenVerified caller's JWT. Omit to use env.APP_OWNER_JWT.
scopeScope 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?)#

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

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

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)#

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

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?)#

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

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

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)#

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

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

SandboxFile#

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

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#