> ## Documentation Index > Fetch the complete documentation index at: https://docs.zode.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a sandbox > Placed at random among active nodes in the region with enough free RAM (weighted by free RAM). Returns once the node reports the sandbox running. An empty body creates a `small` sandbox. The sandbox reads its variables from `?environment=` (an id or a name; the workspace's `default` when absent) at the start of every exec and attach session; unknown is 400 `unknown_environment`. A fork keeps its parent's environment. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/sandboxes openapi: 3.1.0 info: title: Zode API version: 0.1.0 description: Sandboxes for coding agents. Every route takes an API key as a bearer token. servers: - url: https://api.zode.dev security: - bearerAuth: [] tags: - name: Sandboxes - name: Commands - name: Browser and desktop - name: Snapshots - name: Images - name: Environments - name: Flight recorder - name: Attestation - name: Agents - name: Proxying - name: Webhooks - name: OpenTelemetry - name: Alerts - name: CI - name: Usage and billing - name: Workspace - name: Platform paths: /v1/sandboxes: post: tags: - Sandboxes summary: Create a sandbox description: | Placed at random among active nodes in the region with enough free RAM (weighted by free RAM). Returns once the node reports the sandbox running. An empty body creates a `small` sandbox. The sandbox reads its variables from `?environment=` (an id or a name; the workspace's `default` when absent) at the start of every exec and attach session; unknown is 400 `unknown_environment`. A fork keeps its parent's environment. operationId: createSandbox parameters: - name: environment in: query required: false schema: type: string requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/CreateSandboxRequest' responses: '201': description: Created and running content: application/json: schema: $ref: '#/components/schemas/Sandbox' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '402': $ref: '#/components/responses/PlanOrCredit' '403': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/RateLimited' '502': description: >- The node failed; the sandbox is left in status `error` and can be deleted. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: '`no_capacity`: no node in the region has enough free RAM.' content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateSandboxRequest: type: object additionalProperties: false description: | A sandbox is one of the server's sizes, listed by GET /v1/images (`images`, the first is the default). The hosted API has four: | Size | vcpus | ram_mb | disk_gb | |---|---|---|---| | small (the default) | 2 | 4096 | 50 | | default | 4 | 8192 | 50 | | large | 8 | 16384 | 110 | | xlarge | 16 | 32768 | 250 | Leave out `vcpus`, `ram_mb` and `disk_gb` for small. Otherwise send `vcpus`, `ram_mb` or both, plus `disk_gb` if you like: every field sent must match the same size, else 400 `invalid_request` naming the sizes. `disk_gb` alone is 400. The size named `default` (as in the CLI and pricing) is not what an empty request gets. properties: name: type: string pattern: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ vcpus: type: integer enum: - 2 - 4 - 8 - 16 description: Picks the size with this many vCPUs. ram_mb: type: integer enum: - 4096 - 8192 - 16384 - 32768 description: Picks the size with this much RAM. disk_gb: type: integer enum: - 50 - 110 - 250 description: Must be the disk of the size picked by vcpus or ram_mb. region: type: string enum: - eu-central default: eu-central description: '`eu-central` is the only region today; more will be added.' git_repo: type: string maxLength: 512 git_branch: type: string maxLength: 255 pr_number: type: integer minimum: 1 max_cost_micros: type: integer format: int64 minimum: 0 description: >- AI spend cap for this sandbox, in micro-dollars. Counts only AI calls made on the workspace's keys through the node's AI proxy, not compute or storage. The total is kept in the node daemon's memory, so a node daemon restart starts it again from zero. Reaching it refuses further AI calls (402 `zode_spend_cap`) and sends `spend.cap_reached`; the sandbox keeps running. Omitted means the workspace's per-sandbox default. image: type: string description: | A ready custom image of the workspace (img_ id or name). It fixes the size and region: other values give 400. browser: type: boolean description: Switch the browser on; omitted means the workspace default. desktop: type: boolean description: Switch the desktop on; omitted means the workspace default. Sandbox: type: object required: - id - name - status - vcpus - ram_mb - disk_gb - region - git_repo - git_branch - pr_number - max_cost_micros - parent_sandbox_id - created_at - updated_at - deleted_at - created_by properties: id: type: string example: sbx_ilvsd743b36wqi26 name: type: string status: $ref: '#/components/schemas/SandboxStatus' vcpus: type: integer ram_mb: type: integer disk_gb: type: integer region: type: string example: eu-central git_repo: type: string git_branch: type: string pr_number: type: - integer - 'null' max_cost_micros: type: - integer - 'null' format: int64 description: >- AI spend cap for this sandbox, in micro-dollars. Counts only AI calls made on the workspace's keys through the node's AI proxy, not compute or storage. The total is kept in the node daemon's memory, so a node daemon restart starts it again from zero. Reaching it refuses further AI calls (402 `zode_spend_cap`) and sends `spend.cap_reached`; the sandbox keeps running. parent_sandbox_id: type: - string - 'null' created_at: type: string format: date-time updated_at: type: string format: date-time deleted_at: type: - string - 'null' format: date-time browser: type: boolean description: Chrome with CDP is on. desktop: type: boolean description: The Linux desktop is on. feature_error: type: string description: >- Only on a create or fork whose browser or desktop could not be switched on; the sandbox was made. created_by: description: >- The member who created or forked it; null for sandboxes made before this was recorded. oneOf: - type: 'null' - type: object required: - member_id - email properties: member_id: type: string example: mem_ilvsd743b36wqi26 email: type: string description: Kept after the member leaves the workspace. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string examples: - not_found - rate_limited - plan_required description: | Stable machine code; branch on it rather than on `message`. Deliberately not a closed enum: new codes are added over time, so treat an unknown code by its HTTP status. The codes in use, by status (a few appear under two): - 400: `bad_request` (malformed JSON or unknown field), `invalid_request`, `bad_signature`, `confirm_required`, `default_environment`, `email_not_allowed`, `endpoint_required`, `invalid_code`, `invalid_email`, `invalid_image`, `invalid_name`, `invalid_nonce`, `invalid_state`, `invalid_token`, `not_admin`, `order_mismatch`, `org_required`, `owner_cannot_leave`, `password_too_long`, `password_too_short`, `personal_workspace`, `same_email`, `secret_unsupported`, `self`, `too_many`, `unknown_channel`, `unknown_environment`, `unknown_installation`, `url_not_allowed`, `use_transfer` - 401: `unauthorized`, `invalid_credentials`, `bad_signature` - 402: `plan_required` (the plan does not include it), `credit_exhausted` (no credit left and no card on file) - 403: `forbidden` (the role may not), `token_scope`, `csrf`, `cors`, `email_unverified`, `installation_not_yours`, `no_user`, `not_yours`, `subscriptions_off`, `wrong_account`, `wrong_password` - 404: `not_found`, `code_not_found`, `invalid_invite`, `not_configured`, `unknown_node`, `unknown_org`, `unknown_sandbox` - 409: `invalid_state` (wrong sandbox status), `concurrency_limit` (plan's running-sandbox cap), `daily_cap_reached` (workspace daily spend cap), `limit_reached`, `name_taken`, `node_full`, `not_running`, `browser_off`, `desktop_off`, `already_deleted`, `already_linked`, `already_member`, `already_on_plan`, `billing_not_open`, `checkout_required`, `code_not_applicable`, `code_redeemed`, `code_taken`, `endpoint_disabled`, `installation_taken`, `invite_pending`, `last_method`, `no_sandbox`, `not_placed`, `not_waiting`, `sandboxes_running`, `sole_owner`, `too_many_keys`, `trial_unavailable`, `trial_used` - 410: `expired`, `used`, `expired_token`, `expired_invite`, `code_expired`, `code_used_up` - 413: `too_large` - 415: `unsupported_media_type` - 429: `rate_limited` (see the RateLimited response), `too_many_viewers` (desktop viewers) - 500: `internal` - 501 (this server or host cannot do it yet): `feature_unavailable`, `attach_unavailable`, `exec_unavailable`, `snapshots_unavailable`, `images_unavailable`, `recorder_unavailable`, `attestation_unavailable` - 502: `node_error`, `host_unreachable`, `key_destroy_failed`, `provider_error`, `github_error`, `recorder_error` - 503: `no_capacity`, `unhealthy`, `alerts_unavailable`, `auth_unavailable`, `ci_unavailable`, `email_unavailable`, `ingest_unavailable`, `secrets_unavailable`, `webhook_not_ready` The device-flow code and token endpoints answer 400 in the RFC 6749/8628 shape instead (OAuthError). message: type: string SandboxStatus: type: string enum: - creating - running - stopping - stopped - starting - deleting - deleted - error responses: Error: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' PlanOrCredit: description: | `plan_required`: the plan does not include a requested feature (the desktop comes with Pro and up). `credit_exhausted`: the workspace has no payment method on file and its remaining credit is zero or less; add a card or buy credit in Billing. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: | `rate_limited`. Limits are fixed windows per caller, workspace or client IP; the headers describe the window that refused the request. headers: Retry-After: description: Seconds until the window resets. schema: type: integer X-RateLimit-Limit: description: Requests the window allows. schema: type: integer X-RateLimit-Remaining: description: Requests left in the window; always 0 on a 429. schema: type: integer X-RateLimit-Reset: description: When the window resets, in Unix seconds (now plus Retry-After). schema: type: integer format: int64 content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: zode_tok_<64 hex chars> description: >- An API key (`zode_tok_...`). Create one in the console under API keys (https://console.zode.dev/tokens), or with `zode login`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.