API REFERENCE

Create Sandbox

On this page

POST/api/sandboxes

Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run opencode run "<prompt>" in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/sandboxes' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "command": "ls",
  "args": [
    "-la",
    "/home"
  ],
  "cwd": "/home/user",
  "prompt": "create a hello world index.html",
  "account_id": "YOUR_ID"
}'

Request body required

Optional command execution parameters. If command and prompt are both omitted, sandbox is created without running any command. Use prompt as a shortcut for running OpenCode.

application/json

commandstring

The command to execute in the sandbox environment. If omitted, the sandbox is created without running any command.

minLength: 1

argsarray<string>

Optional arguments to pass to the command.

Item properties

string

cwdstring

Optional working directory for command execution.

promptstring

A prompt to pass to OpenCode in the sandbox. When provided, the sandbox will execute opencode run "<prompt>". Cannot be used together with command.

minLength: 1

account_idstring

UUID of the account to create the sandbox for. Only applicable when the authenticated account has access to multiple accounts via organization membership. If not provided, creates the sandbox for the API key's own account.

format: uuid

Responses

200Sandbox created successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success", "error"

sandboxesarray<Sandbox>required

Array of sandbox objects

Item properties

sandboxIdstringrequired

Unique identifier for the sandbox

sandboxStatusstring · enumrequired

Current lifecycle state of the sandbox

Values: "pending", "running", "stopping", "stopped", "failed"

timeoutintegerrequired

Milliseconds remaining before the sandbox stops automatically

createdAtstringrequired

ISO 8601 timestamp when the sandbox was created

format: date-time

runIdstring

Unique identifier for the command execution run. Only present if a command was provided when creating the sandbox. Use this with GET /api/tasks/runs to check the status and retrieve results.

snapshot_idstringnullable

The account's saved snapshot ID used for creating new sandboxes. Null if no snapshot has been saved.

github_repostringnullable

The GitHub repository URL associated with the account's sandbox environment. Used as the filesystem source when restoring sandboxes.

filetreearray<FileTreeEntry>nullable

The recursive file tree of the account's GitHub repository. Null if no github_repo is set or if the fetch fails.

Item properties

pathstringrequired

The file or directory path relative to the repository root

typestring · enumrequired

The type of entry: blob for files, tree for directories

Values: "blob", "tree"

shastringrequired

The SHA hash of the entry

sizeinteger

The size of the file in bytes. Only present for blob entries.

errorstring

Error message (only present if status is error)

400Bad request - failed to create sandbox

application/json

errorstringrequired

Error message describing what went wrong

401Unauthorized - invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong

403Forbidden - account_id is not a member of the organization or account tried to use an account_id they don't have access to

application/json

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "description": "Create a new ephemeral sandbox environment. Optionally executes a command or an OpenCode prompt if provided. Sandboxes are isolated Linux microVMs that can be used to evaluate account-generated code, run AI agent output safely, or execute reproducible tasks. The sandbox will automatically stop after the timeout period. If no command or prompt is provided, the sandbox is created without triggering any background task. Use the prompt parameter as a shortcut to run `opencode run \"<prompt>\"` in the sandbox. Pass account_id to create a sandbox for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.",
  "requestBody": {
    "description": "Optional command execution parameters. If command and prompt are both omitted, sandbox is created without running any command. Use prompt as a shortcut for running OpenCode.",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateSandboxRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Sandbox created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxesResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - failed to create sandbox",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - account_id is not a member of the organization or account tried to use an account_id they don't have access to",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxErrorResponse"
          }
        }
      }
    }
  }
}