Sandboxes

A sandbox is a persistent runtime environment with its own filesystem, git state, and sessions. All endpoints require an Authorization: Bearer <api_key> header.

Create Sandbox

POSThttps://relay.an.dev/v1/sandboxes

Creates a new runtime sandbox for the specified agent. Optionally seed it with files, environment variables, setup commands, and runtime TTL/network overrides on top of the deployed agent defaults.

Request Body

Name	Type	Required	Description
agent	string	Required	Agent slug to use for this sandbox
files	object	Optional	Map of file path → content to seed
envs	object	Optional	Environment variables to set
setup	string[]	Optional	Shell commands to run after creation
timeoutMs	number	Optional	Sandbox TTL in milliseconds. Overrides the deployment default if set. Relay keeps using this TTL when reconnecting and extending the sandbox.
networkAllowOut	string[]	Optional	Allowed outbound domains, IPs, or CIDRs. Overrides the deployment default if set. Relay-required hosts are always appended automatically.
networkDenyOut	string[]	Optional	Denied outbound IPs or CIDRs. Overrides the deployment default if set. Relay-required hosts remain allowed.

Request Body

{
  "agent": "my-agent",
  "files": { "/home/user/workspace/config.json": "{\"key\": \"value\"}" },
  "envs": { "NODE_ENV": "production" },
  "setup": ["npm install -g prettier"],
  "timeoutMs": 1800000,
  "networkAllowOut": ["api.github.com"],
  "networkDenyOut": ["1.1.1.1"]
}

Use timeoutMs to control the runtime sandbox TTL. If the deployed agent already sets default TTL or network rules in Sandbox(...), the request values here override those defaults. Relay still preserves the outbound hosts it needs for proxying and streaming.

Response

{
  "id": "sb_abc123",
  "sandboxId": "e2b-sandbox-id",
  "status": "active",
  "createdAt": "2026-02-26T12:00:00Z"
}

cURL

curl -X POST https://relay.an.dev/v1/sandboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-agent",
    "files": { "/home/user/workspace/config.json": "{\"key\": \"value\"}" },
    "setup": ["npm install -g prettier"],
    "timeoutMs": 1800000,
    "networkAllowOut": ["api.github.com"],
    "networkDenyOut": ["1.1.1.1"]
  }'

Get Sandbox

GEThttps://relay.an.dev/v1/sandboxes/:id

Retrieves details about an existing sandbox including its agent, threads, and current status.

Path Parameters

Name	Type	Required	Description
id	string	Required	Sandbox ID

Response

{
  "id": "sb_abc123",
  "sandboxId": "e2b-sandbox-id",
  "status": "active",
  "error": null,
  "agent": { "slug": "my-agent", "name": "My Agent" },
  "threads": [
    { "id": "th_xyz789", "name": "Chat 1", "status": "completed" }
  ],
  "createdAt": "2026-02-26T12:00:00Z",
  "updatedAt": "2026-02-26T12:05:00Z"
}

cURL

curl https://relay.an.dev/v1/sandboxes/sb_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete Sandbox

DELETEhttps://relay.an.dev/v1/sandboxes/:id

Deletes the sandbox and cascades deletion to all threads within it. Returns 204 No Content on success.

Path Parameters

Name	Type	Required	Description
id	string	Required	Sandbox ID

Returns 204 No Content on success.

cURL

curl -X DELETE https://relay.an.dev/v1/sandboxes/sb_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"