# Create Sandbox Source: https://recoupable.dev/docs/api-reference/sandboxes/create 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 ""` 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. ## POST /api/sandboxes Full OpenAPI specification: https://recoupable.dev/docs/spec/content.json ## Authentication The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it. [Authentication guide](https://recoupable.dev/docs/authentication) ## Operation and referenced schemas ```json { "openapi": "3.1.0", "info": { "title": "Recoup API - Content", "description": "API documentation for the Recoup platform - an AI agent platform for the music industry", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.recoupable.dev" } ], "paths": { "/api/sandboxes": { "post": { "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 \"\"` 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" } } } } } } } }, "components": { "schemas": { "CreateSandboxRequest": { "type": "object", "description": "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.", "properties": { "command": { "type": "string", "minLength": 1, "description": "The command to execute in the sandbox environment. If omitted, the sandbox is created without running any command.", "example": "ls" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Optional arguments to pass to the command.", "example": [ "-la", "/home" ] }, "cwd": { "type": "string", "description": "Optional working directory for command execution.", "example": "/home/user" }, "prompt": { "type": "string", "minLength": 1, "description": "A prompt to pass to OpenCode in the sandbox. When provided, the sandbox will execute `opencode run \"\"`. Cannot be used together with command.", "example": "create a hello world index.html" }, "account_id": { "type": "string", "format": "uuid", "description": "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." } } }, "SandboxesResponse": { "type": "object", "required": [ "status", "sandboxes" ], "description": "Response containing sandbox information", "properties": { "status": { "type": "string", "enum": [ "success", "error" ], "description": "Status of the request" }, "sandboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Sandbox" }, "description": "Array of sandbox objects" }, "snapshot_id": { "type": "string", "description": "The account's saved snapshot ID used for creating new sandboxes. Null if no snapshot has been saved.", "example": "snap_abc123def456", "nullable": true }, "github_repo": { "type": "string", "description": "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", "nullable": true }, "filetree": { "type": "array", "nullable": true, "description": "The recursive file tree of the account's GitHub repository. Null if no github_repo is set or if the fetch fails.", "items": { "$ref": "#/components/schemas/FileTreeEntry" } }, "error": { "type": "string", "description": "Error message (only present if status is error)" } } }, "SandboxErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Error message describing what went wrong", "example": "Failed to create sandbox" } } }, "Sandbox": { "type": "object", "required": [ "sandboxId", "sandboxStatus", "timeout", "createdAt" ], "description": "A sandbox environment instance", "properties": { "sandboxId": { "type": "string", "description": "Unique identifier for the sandbox", "example": "sbx_abc123def456" }, "sandboxStatus": { "type": "string", "enum": [ "pending", "running", "stopping", "stopped", "failed" ], "description": "Current lifecycle state of the sandbox", "example": "running" }, "timeout": { "type": "integer", "description": "Milliseconds remaining before the sandbox stops automatically", "example": 300000 }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the sandbox was created", "example": "2024-01-15T10:30:00.000Z" }, "runId": { "type": "string", "description": "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](/api-reference/tasks/runs) to check the status and retrieve results.", "example": "run_xyz789abc123" } } }, "FileTreeEntry": { "type": "object", "required": [ "path", "type", "sha" ], "description": "A single entry in a GitHub repository file tree", "properties": { "path": { "type": "string", "description": "The file or directory path relative to the repository root", "example": "src/index.ts" }, "type": { "type": "string", "enum": [ "blob", "tree" ], "description": "The type of entry: blob for files, tree for directories" }, "sha": { "type": "string", "description": "The SHA hash of the entry", "example": "abc123def456" }, "size": { "type": "integer", "description": "The size of the file in bytes. Only present for blob entries.", "example": 1024 } } } } } } ```