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

# Capture a snapshot from a sandbox

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

## Request

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

Create a snapshot by capturing the current state of a sandbox or promoting an existing checkpoint.

## Path parameters

- `name` string, required

## Request body

- SandboxesCaptureSnapshotPayload
  - `checkpoint` string: if omitted, creates a fresh checkpoint from the running VM
  - `confirm_allow_snapshot_secret_values` boolean: Must be true when the included settings hold literal secret values (opaque values rather than workspace secret references, and any env var value), acknowledging that the snapshot stores them and every sandbox created from it can use them.
  - `description` string: Description says what this snapshot's image can do, so a caller can hand it to an agent as a capability summary. At most 1024 characters.
  - `docker_image` string: sandbox-local Docker image to export
  - `fs_capacity_bytes` integer: required for Docker image export unless the sandbox has a capacity
  - `image_config` SandboxesSnapshotImageConfig
    - `cmd` string[]: Cmd follows Entrypoint, as CMD: its arguments, or the whole command when Entrypoint is empty.
    - `entrypoint` string[]: Entrypoint is the program the command starts with, as ENTRYPOINT.
    - `exposed_ports` integer[]: ExposedPorts are the TCP ports the command listens on, as EXPOSE.
  - `include` string[]: Sandbox settings to carry into the snapshot. Sandboxes created from it start with each carried setting their create request leaves unset: "mounts" (the mount_config, with its auth), "proxy_config", "env_vars", "resources" (CPU and memory), "lifecycle" (idle_ttl_seconds, delete_after_stop_seconds, preserve_memory_on_stop), and "labels" (merged under this request's labels; reserved com.langchain.* labels are left out). "all" names every one of these. VM memory is captured with include_memory, not here. Warning: mounts, proxy_config and env_vars carry the sandbox's credentials, and every sandbox created from the snapshot can use them.
  - `include_memory` boolean: IncludeMemory, when true, captures a full VM memory snapshot alongside the filesystem clone. Only honored when the sandbox is running AND Checkpoint is omitted (i.e. a fresh in-VM checkpoint is requested). Defaults to false to keep snapshots small unless memory restore is explicitly desired.
  - `labels` SandboxesLabels
  - `name` string, required
  - `run_config` SandboxapiRunConfig
    - `env_vars` object
    - `user` string
    - `work_dir` string
  - `tag` string: mutable Docker-style tag; defaults to "latest"

## Response `201`

Created

- SandboxesSnapshotResponse
  - `created_at` string
  - `created_by` string
  - `description` string: Description says what this snapshot's image can do, so a caller can hand it to an agent as a capability summary.
  - `docker_image` string
  - `fs_capacity_bytes` integer
  - `fs_used_bytes` integer
  - `id` string
  - `image_digest` string
  - `included` string[]: The settings this snapshot carries, in include terms: sandboxes created from it start with each one their create request leaves unset. Env var values are never returned.
  - `labels` SandboxesLabels
  - `memory_snapshot_size_bytes` integer: MemorySnapshotSizeBytes is non-nil iff the snapshot was captured with VM memory state. A non-nil value is the canonical signal that this snapshot can warm-restore from memory; nil means rootfs only.
  - `mount_config` SandboxesSandboxMountConfig (unresolved $ref)
  - `name` string
  - `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)
  - `registry_id` string
  - `run_config` SandboxapiRunConfig
    - `env_vars` object
    - `user` string
    - `work_dir` string
  - `source_sandbox_id` string
  - `status` string
  - `status_message` string
  - `tags` string[]: Tags currently resolving to this snapshot, under Name. A snapshot with no tags is dangling — addressable only by id.
  - `updated_at` string

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: sandbox must be running for Docker image export
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-26** `dfe647d1748e`: 1 info
  - added the optional property `proxy_config/allOf[#/components/schemas/sandboxes.ProxyConfig]/rules/items/relay_id` to the response with the `201` status
- **2026-10-23** `5dfd05c0b870`: 1 info
  - added the new optional request property `image_config`
- **2026-10-19** `9aeaab9f0a28`: 5 info
  - added the new optional request property `confirm_allow_snapshot_secret_values`
  - added the new optional request property `include`
  - added the optional property `included` to the response with the `201` status
  - added the optional property `mount_config` to the response with the `201` 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/snapshot/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)