Sandboxes API

Authentication

Most requests require a Bearer token. Pass your API or SDK key in the Authorization header. Public endpoints (such as listing and fetching public snapshots) are noted below and do not require authentication.

You can find your SDK key in the Agentuity Console under your project settings.

Sandbox Management

Create Sandbox

Create a new sandbox execution environment.

Parameters

Request Body

Sandbox creation payload.

Response

Returns the sandbox ID, status, and optional stream URLs for stdout/stderr.

Response Fields

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "dev-sandbox",
  "runtime": "node-20",
  "resources": {
    "memory": 512
  },
  "env": {
    "NODE_ENV": "development"
  }
}'

List Sandboxes

List sandboxes with optional filtering and pagination.

Parameters

Response

Returns paginated list of sandboxes.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Sandbox

Retrieve a specific sandbox by ID.

Parameters

Response

Returns full sandbox details including resources, runtime, network, timeout, and usage metrics.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Destroy Sandbox

Destroy a sandbox and release all resources.

Parameters

Response

Destroys the sandbox and releases all resources.

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Sandbox Status

Lightweight status check backed by Redis (~1ms). Optimized for polling.

Parameters

Response

Returns the sandbox status.

Response Fields

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/status/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Pause Sandbox

Pause a running sandbox and create a checkpoint.

Parameters

Response

Pauses the sandbox and creates a checkpoint.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123/pause' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Resume Sandbox

Resume a paused sandbox from its checkpoint.

Parameters

Response

Resumes a paused sandbox from its checkpoint.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123/resume' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Update Environment

Update environment variables for a sandbox. Set a value to null to delete a variable.

Parameters

Request Body

Environment variable updates.

Response

Returns the current environment after update.

Response Fields

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/sandbox/env/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "env": {
    "NODE_ENV": "production",
    "OLD_VAR": null
  }
}'

Execution

Execute Command

Execute a command in a sandbox.

Parameters

Request Body

Command execution payload.

Response

Returns execution ID and stream URLs. If the sandbox was suspended, it is automatically resumed and the response includes autoResumed: true. Returns 409 if sandbox is busy.

Response Fields

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123/execute' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "command": [
    "node",
    "-e",
    "console.log('\''hello'\'')"
  ]
}'

Get Execution

Retrieve execution details. Use the wait parameter for long-polling.

Parameters

Response

Returns execution details. Use the wait parameter for long-polling.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/execution/exec_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Executions

List executions for a specific sandbox.

Parameters

Response

Returns list of executions for the sandbox.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/sandboxes/sbx_abc123/executions' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Events

List Events

List lifecycle events for a specific sandbox. Events are returned in chronological order (oldest first) by default.

Parameters

Response

Returns list of lifecycle events for the sandbox.

Response Fields

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/sandboxes/sbx_abc123/events' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

File System

Write Files

Write one or more files to the sandbox filesystem.

Parameters

Request Body

Files to write.

Response

Returns the number of files written.

Response Fields

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/fs/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "files": [
    {
      "path": "/app/index.js",
      "content": "Y29uc29sZS5sb2coJ2hlbGxvJyk="
    }
  ]
}'

Read File

Read a file from the sandbox filesystem.

Parameters

Response

Returns the raw file contents as a stream.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/fs/sbx_abc123?path=/home/user/file.txt' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Create Directory

Create a directory in the sandbox filesystem.

Parameters

Request Body

Directory creation payload.

Response

Directory created successfully.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/fs/mkdir/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "/app/src",
  "recursive": true
}'

Remove Directory

Remove a directory from the sandbox filesystem.

Parameters

Request Body

Directory removal payload.

Response

Directory removed successfully.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/fs/rmdir/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "/app/tmp",
  "recursive": true
}'

Remove File

Remove a file from the sandbox filesystem.

Parameters

Request Body

File removal payload.

Response

File removed successfully.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/fs/rm/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "path": "/app/old-file.js"
}'

List Files

List files in a sandbox directory.

Parameters

Response

Returns list of files in the directory.

Response Fields

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/fs/list/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Download Archive

Download a compressed archive of the sandbox filesystem.

Parameters

Response

Returns a streaming archive of the sandbox filesystem.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/fs/download/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Upload Archive

Upload and extract a compressed archive to the sandbox. Send raw binary with Content-Type: application/octet-stream.

Parameters

Response

Uploads and extracts a compressed archive to the sandbox. Send raw binary with Content-Type: application/octet-stream.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/fs/upload/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/octet-stream' \
  -d '<binary archive data>'

Snapshots

Create Snapshot

Create a snapshot of the sandbox filesystem.

Parameters

Request Body

Snapshot creation payload.

Response

Returns the created snapshot.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123/snapshot' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "baseline",
  "tag": "v1.0"
}'

Get Snapshot

Retrieve a specific snapshot by ID.

Parameters

Response

Returns the snapshot object.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/snp_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Snapshots

List snapshots with optional filtering and pagination.

Parameters

Response

Returns paginated list of snapshots.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Snapshot

Delete a snapshot.

Parameters

Response

Empty response on success.

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/snp_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Update Snapshot Tag

Update the tag on a snapshot.

Parameters

Request Body

Tag update payload.

Response

Returns the updated snapshot.

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/snp_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "tag": "v2.0"
}'

Get Snapshot Lineage

Get the ordered ancestry chain from a specified snapshot to root.

Parameters

Response

Returns ordered ancestry chain from specified snapshot to root.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/lineage' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Public Snapshot

Retrieve a public snapshot by ID, full name (@slug/name:tag), or name:tag. No authentication required.

Parameters

Response

Returns public snapshot details. No authentication required.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/public/snp_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Public Snapshots

List publicly available snapshots.

Parameters

Response

Returns paginated list of public snapshots.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/public' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Initialize Snapshot Build

Initialize a snapshot build. Returns a presigned upload URL for the snapshot archive.

Parameters

Request Body

Snapshot build initialization payload.

Response

Returns snapshot ID and presigned upload URL. If unchanged is true, content matches existing snapshot.

Response Fields

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/build' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "runtime": "node-20",
  "name": "my-app",
  "tag": "latest"
}'

Finalize Snapshot Build

Finalize a snapshot build after uploading the archive.

Parameters

Request Body

Snapshot finalization payload.

Response

Returns the finalized snapshot.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/snp_abc123/finalize' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "sizeBytes": 1048576,
  "fileCount": 42,
  "files": [
    {
      "path": "/app/index.js",
      "size": 1024
    }
  ]
}'

Upload Public Snapshot

Upload a gzip archive for public snapshots. Content-Type must be application/gzip. Includes virus scanning.

Parameters

Response

Uploads a gzip archive for public snapshots. Content-Type must be application/gzip. Includes virus scanning.

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/sandbox/snapshots/snp_abc123/upload' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/gzip' \
  -d '<binary gzip data>'

Sandbox Checkpoints

Create Checkpoint

Create a named checkpoint of the sandbox filesystem. Checkpoint names must be unique — creating a checkpoint with a name that already exists returns 409 Conflict. Checkpoints are persisted across pause/resume cycles.

Parameters

Request Body

Checkpoint creation payload.

Response

Returns the created checkpoint.

Response Fields

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123/checkpoint' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "before-migration"
}'

List Checkpoints

List checkpoints for a specific sandbox. Checkpoints are persisted across pause/resume cycles.

Parameters

Response

Returns list of checkpoints for the sandbox.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/checkpoints/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Restore Checkpoint

Restore the sandbox filesystem to a checkpoint state.

Parameters

Response

Restores the sandbox filesystem to the checkpoint state.

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123/checkpoint/ckpt_def456/restore' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Checkpoint

Delete a checkpoint.

Parameters

Response

Empty response on success.

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/sandbox/sbx_abc123/checkpoint/ckpt_def456' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Runtimes

List Runtimes

List available sandbox runtimes with their requirements.

Parameters

Response

Returns available sandbox runtimes with their requirements.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/sandbox/runtimes' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

CLI Endpoints

List Sandboxes (Cross-Org)

List sandboxes across all organizations the user belongs to.

Parameters

Response

Lists sandboxes across all organizations the user belongs to.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/sandbox' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Resolve Sandbox

Resolve a sandbox ID to its org, region, and project. Used for cross-org sandbox lookup.

Parameters

Response

Resolves a sandbox ID to its org, region, and project. Used for cross-org sandbox lookup.

Response Fields

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/cli/sandbox/sbx_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'