Skip to main content
POST
/
api
/
sandboxes
cURL
curl --request POST \
  --url https://recoup-api.vercel.app/api/sandboxes \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "ls",
  "args": [
    "-la",
    "/home"
  ],
  "cwd": "/home/user",
  "prompt": "create a hello world index.html",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{
  "status": "success",
  "sandboxes": [
    {
      "sandboxId": "sbx_abc123def456",
      "sandboxStatus": "running",
      "timeout": 300000,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "runId": "run_xyz789abc123"
    }
  ],
  "snapshot_id": "snap_abc123def456",
  "github_repo": "https://github.com/username/repo",
  "filetree": [
    {
      "path": "src/index.ts",
      "type": "blob",
      "sha": "abc123def456",
      "size": 1024
    }
  ],
  "error": "<string>"
}

Body

application/json

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.

Request body for creating a new sandbox. All fields are optional - if no command or prompt is provided, sandbox is created without triggering a command execution task. Use prompt as a shortcut to run OpenCode with a given prompt instead of specifying command/args manually.

​
command
string

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

Minimum string length: 1
Example:

"ls"

​
args
string[]

Optional arguments to pass to the command.

Example:
["-la", "/home"]
​
cwd
string

Optional working directory for command execution.

Example:

"/home/user"

​
prompt
string

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

Minimum string length: 1
Example:

"create a hello world index.html"

​
account_id
string<uuid>

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.

Response

Sandbox created successfully

Response containing sandbox information

​
status
enum<string>
required

Status of the request

Available options:
success,
error
​
sandboxes
object[]
required

Array of sandbox objects

​
snapshot_id
string | null

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

Example:

"snap_abc123def456"

​
github_repo
string | null

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

Example:

"https://github.com/username/repo"

​
filetree
object[] | null

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

​
error
string

Error message (only present if status is error)