---
title: "Create a sandbox"
method: POST
path: "/api/v2/sandboxes/boxes"
tags: ["sandboxes"]
---

# Create a sandbox

`POST /api/v2/sandboxes/boxes`

## Request

- Base URL: `https://api.smith.langchain.com`
- URL: `https://api.smith.langchain.com/api/v2/sandboxes/boxes`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in header `X-Tenant-Id`
  - HTTP bearer
  - `X-Service-Key` (a scheme the document does not define)

Create a new sandbox from a snapshot. Provide at most one of `snapshot_id` or `snapshot_name`; if neither is provided, the server uses the default snapshot. `snapshot_name` accepts a Docker-style `name` or `name:tag` reference (a bare name resolves to `name:latest`).

## Request body

- SandboxesCreateSandboxPayload
  - `access_delegation` SandboxesAccessDelegation
    - `mode` 'INHERIT' | 'EXPLICIT', required
    - `permissions` string[]
  - `cpu_millicores` integer: CPUMillicores optionally requests CPU at millicore granularity (e.g. 500 = 0.5 vCPU); takes precedence over VCPUs. Fractional (sub-vCPU) values are not available for every sandbox.
  - `delete_after_stop_seconds` integer
  - `env_vars` object
  - `fs_capacity_bytes` integer
  - `idle_ttl_seconds` integer
  - `labels` SandboxesLabels
  - `mem_bytes` integer: Memory for the sandbox, in bytes. Memory is tied to CPU at 4 GiB per vCPU: omit it and it follows that ratio; set it and it must stay within 50% of the ratio for the requested CPU, so a 1 vCPU sandbox accepts 2-6 GiB. Setting memory without CPU derives the CPU from the same ratio. Maximum 64 GiB.
  - `mount_config` SandboxesSandboxMountConfig (unresolved $ref)
  - `name` string
  - `persistent` boolean: Persistent (private beta) keeps the sandbox's filesystem across stops (the default, true). Set it to false for a disposable sandbox: its writes are discarded whenever it stops, the next start boots it fresh from its snapshot, and it is never charged for storage. A sandbox that is not persistent cannot preserve memory on stop or have its filesystem captured as a snapshot (exporting a Docker image from it with docker_image still works), and some snapshots captured from other sandboxes cannot start one; such a create is rejected. Setting it to false requires the private beta to be enabled for your workspace.
  - `preserve_memory_on_stop` boolean: PreserveMemoryOnStop, when true, suspends the sandbox's memory on a voluntary stop (idle timeout or explicit stop) so the next start resumes from where it left off. Default false discards memory and keeps only the filesystem, so the next start is a cold boot. Restarts triggered by infrastructure maintenance always preserve memory regardless of this setting.
  - `proxy_config` SandboxesProxyConfig
    - `access_control` SandboxesAccessControl
      - `allow_list` string[]
      - `deny_list` string[]
    - `callbacks` SandboxesCallback[]
      - `full_request` boolean
      - `match_hosts` string[], required
      - `request_headers` SandboxesProxyHeader[]
        - `is_set` boolean
        - `name` string, required
        - `type` 'plaintext' | 'opaque' | 'workspace_secret', required
        - `value` string
      - `ttl_seconds` integer, required
      - `url` string, required
    - `description` string: Description says what this configuration as a whole lets the sandbox reach, complementing the per-rule descriptions. At most 1024 characters.
    - `no_proxy` string[]
    - `rules` SandboxesProxyRule[] (unresolved $ref)
  - `restore_memory` boolean: RestoreMemory selects how the sandbox handles a snapshot's captured memory: nil → if-present: resume from memory when the snapshot has it, else cold-boot (default). true → always: resume from memory; rejected if the snapshot has none. false → never: always cold-boot. Applies to this request only.
  - `run_config` SandboxapiRunConfig
    - `env_vars` object
    - `user` string
    - `work_dir` string
  - `snapshot` string: Snapshot is a Docker-style name or name:tag reference to boot from. A bare name resolves to name:latest.
  - `snapshot_id` string
  - `snapshot_name` string: SnapshotName is a synonym for Snapshot, accepted for compatibility with clients that predate it. Set one or the other.
  - `tag_value_ids` string[]
  - `vcpus` integer
  - `volumes` SandboxesVolumeMountRequest[]: Volumes (beta) attaches existing volumes at mount paths inside the sandbox. At most 4; requires sandbox volumes to be enabled for your workspace. Attaching a volume requires being its creator or holding sandboxes:exec.
    - `mount_path` string, required: MountPath is the absolute directory inside the sandbox where the volume appears.
    - `read_only` boolean: ReadOnly mounts the volume read-only; many sandboxes may do so at once.
    - `volume` string, required: Volume is the volume's ID or name.

## Response `201`

Created

- SandboxesSandboxResponse
  - `access_delegation` SandboxesAccessDelegation
    - `mode` 'INHERIT' | 'EXPLICIT', required
    - `permissions` string[]
  - `cpu_millicores` integer
  - `created_at` string
  - `created_by` string
  - `dataplane_url` string
  - `delete_after_stop_seconds` integer
  - `fs_capacity_bytes` integer
  - `id` string
  - `idle_ttl_seconds` integer
  - `labels` SandboxesLabels
  - `mem_bytes` integer
  - `mount_config` SandboxesSandboxMountConfig (unresolved $ref)
  - `name` string
  - `persistent` boolean: Persistent (private beta) reports whether the sandbox keeps its filesystem across stops. When false, its writes are discarded whenever it stops and it is not charged for storage.
  - `preserve_memory_on_stop` boolean
  - `proxy_config` SandboxesProxyConfig
    - `access_control` SandboxesAccessControl
      - `allow_list` string[]
      - `deny_list` string[]
    - `callbacks` SandboxesCallback[]
      - `full_request` boolean
      - `match_hosts` string[], required
      - `request_headers` SandboxesProxyHeader[]
        - `is_set` boolean
        - `name` string, required
        - `type` 'plaintext' | 'opaque' | 'workspace_secret', required
        - `value` string
      - `ttl_seconds` integer, required
      - `url` string, required
    - `description` string: Description says what this configuration as a whole lets the sandbox reach, complementing the per-rule descriptions. At most 1024 characters.
    - `no_proxy` string[]
    - `rules` SandboxesProxyRule[] (unresolved $ref)
  - `run_config` SandboxapiRunConfig
    - `env_vars` object
    - `user` string
    - `work_dir` string
  - `size_class` string
  - `snapshot_id` string
  - `status` string
  - `status_message` string
  - `stopped_at` string
  - `updated_at` string
  - `updated_by` string
  - `vcpus` integer
  - `volumes` SandboxesSandboxVolumeResponse[]: Volumes (beta) are the volumes attached to the sandbox, in slot order. Absent when the workspace does not have sandbox volumes enabled.
    - `mount_path` string
    - `read_only` boolean
    - `volume_id` string
    - `volume_name` string

## Other responses

- `400`: Snapshot not found
- `403`: A requested feature is not enabled for this workspace
- `409`: Name already exists
- `422`: Validation error
- `429`: Quota exceeded
- `500`: Sandbox creation failed or internal error
- `504`: Sandbox did not become ready in time

## Changes

- **2026-10-26** `dfe647d1748e`: 7 info
  - added the new optional request property `persistent`
  - added the new optional request property `proxy_config/rules/items/relay_id`
  - added the new optional request property `volumes`
  - added the non-success response with the status `403`
  - …3 more
- **2026-10-16** `1a8ee9358d81`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langchain-ai/apis/langsmith/changes/api/v2/sandboxes/boxes/post.md)

---

[API](https://skmtc.dev/langchain-ai/apis/langsmith.md) - [All operations](https://skmtc.dev/langchain-ai/apis/langsmith/llms.txt) - [OpenAPI document](https://skmtc.dev/langchain-ai/apis/langsmith/revisions/7a01c01f75e8?raw)