> ## Documentation Index > Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Sandbox > 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. ## OpenAPI ````yaml api-reference/openapi/content.json POST /api/sandboxes 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 security: [] 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 ````