Create a sandbox

agent (claude or codex) and projectId are required; every other field falls back to the project's defaults, the selected profile, or a server-generated value. profile picks a workload shape (auto, agent-small, agent-standard, build-heavy, browser-heavy, repo-large or long-running), and machineSize overrides its initial machine tier. region picks where it runs; an unavailable region is refused rather than replaced. Infrastructure tier comes from the org's plan. endUserId and metadata attribute the sandbox to one of your own users. The sandbox is returned while it is still provisioning; poll GET /sandboxes/{sandboxId} until it is ready.

Authorization

bearerAuth

AuthorizationBearer <token>

A RemoteHost API key (rh_sk_...) or a user session token.

In: header

Path Parameters

orgId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agent?string

projectId?string

profile?string

machineSize?string

vmm?string

The VMM (virtual machine monitor) the sandbox runs on. Left out: its template's when it boots from a custom template, else its environment's VMM, else the org's default. Refused with 409 vmm_mismatch when it differs from its template's, and with 409 vmm_unavailable when none of the hosts the org's sandboxes may be placed on can run it. Refused with 400 until VMM choice is enabled for this deployment.

Value in

"qemu"
"firecracker"

region?string

name?string

sshPublicKey?string

persistencePolicy?string

mode?string

ttlSeconds?number

Seconds until the sandbox auto-stops (pause for persistent policies, delete for throwaway_ephemeral). Defaults to 3600; capped by the plan's session limit; ignored for always_on. Must be from 0 to 31536000 (one year) in every mode, always_on included; a value outside that range is refused with 400 invalid_body.

endUserId?string

metadata?

templateId?string

environmentId?string

An environment of this project to boot from. It supplies the template and machine size unless the request names them, and always its egress policy, environment variables and setup script; the egress policy is re-applied on every wake. Refused if the policy cannot reach one of the project's repositories (SSH deploy keys need the full policy). Optional: a sandbox created without one has unrestricted network access, unless the project's default environment is enforced: then every sandbox boots from that default, whatever the caller's role, and naming another environment, or a templateId other than its own, is refused (403 environment_enforced).

Response Body

`application/json`

curl -X POST "https://example.com/orgs/string/sandboxes" \  -H "Content-Type: application/json" \  -d '{}'

{  "sandbox": {    "id": "string",    "org_id": "string",    "project_id": "string",    "name": "string",    "agent": "claude",    "status": "provisioning",    "mode": "persistent",    "region": "string",    "persistence_policy": "throwaway_ephemeral",    "sandbox_profile": "string",    "machine_size": "small",    "provider": "string",    "vmm": "string",    "allocated_vcpu": 0,    "allocated_memory_gb": 0,    "allocated_disk_gb": 0,    "end_user_id": "string",    "vm_lost_at": "string",    "environment_id": "string",    "disk": {      "usedBytes": 0,      "totalBytes": 0,      "availableBytes": 0,      "warning": 80,      "sampledAt": "string"    },    "created_at": "string",    "updated_at": "string"  },  "repoWarnings": [    "string"  ]}

Create a sandbox

Authorization

Path Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

408application/json

409application/json

413application/json

429application/json

500application/json

503application/json

504application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`