---
title: "Start a sandbox"
method: POST
path: "/api/v2/sandboxes/boxes/{name}/start"
tags: ["sandboxes"]
---

# Start a sandbox

`POST /api/v2/sandboxes/boxes/{name}/start`

## Request

- Base URL: `https://api.smith.langchain.com`
- URL: `https://api.smith.langchain.com/api/v2/sandboxes/boxes/{name}/start`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in header `X-Tenant-Id`
  - HTTP bearer

Start a stopped or failed sandbox. This endpoint is not idempotent. The optional volumes field is beta and requires sandbox volumes to be enabled for your workspace. Omit it to keep attachments, or send an empty array to detach all volumes. Changing attachments requires a stopped or failed sandbox, runtime access to it (its creator or sandboxes:exec), and, for each newly attached volume, being its creator or holding sandboxes:exec. A start whose volumes differ from those the sandbox's saved memory was captured with fails with 409 unless discard_memory is set, which cold-boots the sandbox without that memory.

## Path parameters

- `name` string, required

## Request body

- SandboxesStartSandboxPayload
  - `discard_memory` boolean: DiscardMemory cold-boots the sandbox, discarding any memory saved when it stopped.
  - `volumes` SandboxesVolumeMountRequest[]: Volumes, when present, replaces the attached volumes. A start whose volumes differ from those the sandbox's saved memory was captured with fails unless discard_memory is set.
    - `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 `202`

Accepted

- 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`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: volumes cannot change now, or would discard saved memory
- `500`: Internal Server Error

## Changes

- **2026-10-26** `dfe647d1748e`: 5 info
  - added optional request body
  - added the non-success response with the status `409`
  - added the optional property `persistent` to the response with the `202` status
  - added the optional property `proxy_config/rules/items/relay_id` to the response with the `202` status
  - …1 more
- **2026-10-16** `1a8ee9358d81`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langchain-ai/apis/langsmith/changes/api/v2/sandboxes/boxes/:name/start/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)