Create a sandbox

Error

A valid request URL is required to generate request examples

{
  "access_delegation": {
    "mode": "INHERIT",
    "permissions": [
      "<string>"
    ]
  },
  "cpu_millicores": 123,
  "created_at": "<string>",
  "created_by": "<string>",
  "dataplane_url": "<string>",
  "delete_after_stop_seconds": 123,
  "fs_capacity_bytes": 123,
  "id": "<string>",
  "idle_ttl_seconds": 123,
  "labels": {},
  "mem_bytes": 123,
  "mount_config": {
    "auth": {
      "aws": {
        "role_arn": "<string>",
        "subject_scope": "<string>"
      },
      "azure": {
        "tenant_id": "<string>",
        "client_id": "<string>",
        "subject_scope": "<string>"
      },
      "gcp": {
        "workload_identity_provider": "<string>",
        "service_account_email": "<string>",
        "subject_scope": "<string>"
      }
    },
    "mounts": [
      {
        "id": "<string>",
        "mount_path": "<string>",
        "s3": {
          "bucket": "<string>",
          "region": "<string>",
          "endpoint_url": "<string>",
          "path_style": true,
          "prefix": "<string>"
        },
        "type": "s3",
        "cache": {
          "max_size_bytes": 1,
          "writeback_seconds": 1
        },
        "encryption": {
          "kms_key": "<string>"
        },
        "read_only": true,
        "azure_blob": {
          "container": "<string>",
          "storage_account": "<string>",
          "prefix": "<string>"
        },
        "contexthub": {
          "repo": "<string>",
          "initial_pull_only": true
        },
        "gcs": {
          "bucket": "<string>",
          "prefix": "<string>"
        },
        "git": {
          "remote_url": "<string>",
          "ref": {
            "name": "<string>",
            "type": "branch"
          },
          "refresh_interval_seconds": 2
        }
      }
    ]
  },
  "name": "<string>",
  "persistent": true,
  "preserve_memory_on_stop": true,
  "proxy_config": {
    "access_control": {
      "allow_list": [
        "<string>"
      ],
      "deny_list": [
        "<string>"
      ]
    },
    "callbacks": [
      {
        "match_hosts": [
          "<string>"
        ],
        "ttl_seconds": 1830,
        "url": "<string>",
        "full_request": true,
        "request_headers": [
          {
            "name": "<string>",
            "type": "plaintext",
            "is_set": true,
            "value": "<string>"
          }
        ]
      }
    ],
    "description": "<string>",
    "no_proxy": [
      "<string>"
    ],
    "rules": [
      {
        "name": "<string>",
        "aws": {
          "role_arn": "<string>",
          "subject_scope": "<string>"
        },
        "azure": {
          "tenant_id": "<string>",
          "client_id": "<string>",
          "subject_scope": "<string>",
          "resources": [
            "https://storage.azure.com"
          ]
        },
        "description": "<string>",
        "enabled": true,
        "env_vars": {},
        "gcp": {
          "workload_identity_provider": "<string>",
          "service_account_email": "<string>",
          "subject_scope": "<string>",
          "scopes": [
            "<string>"
          ]
        },
        "headers": [
          {
            "name": "<string>",
            "type": "plaintext",
            "is_set": true,
            "value": "<string>"
          }
        ],
        "match_headers": [
          "<string>"
        ],
        "match_hosts": [
          "<string>"
        ],
        "match_paths": [
          "<string>"
        ],
        "relay_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "rewrite": {
          "port": 32768,
          "credentials": "strip",
          "host": "<string>",
          "sandbox": "<string>"
        },
        "type": "<string>"
      }
    ]
  },
  "run_config": {
    "env_vars": {},
    "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": 123,
  "volumes": [
    {
      "mount_path": "<string>",
      "read_only": true,
      "volume_id": "<string>",
      "volume_name": "<string>"
    }
  ]
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

POST

api

sandboxes

boxes

Error

A valid request URL is required to generate request examples

{
  "access_delegation": {
    "mode": "INHERIT",
    "permissions": [
      "<string>"
    ]
  },
  "cpu_millicores": 123,
  "created_at": "<string>",
  "created_by": "<string>",
  "dataplane_url": "<string>",
  "delete_after_stop_seconds": 123,
  "fs_capacity_bytes": 123,
  "id": "<string>",
  "idle_ttl_seconds": 123,
  "labels": {},
  "mem_bytes": 123,
  "mount_config": {
    "auth": {
      "aws": {
        "role_arn": "<string>",
        "subject_scope": "<string>"
      },
      "azure": {
        "tenant_id": "<string>",
        "client_id": "<string>",
        "subject_scope": "<string>"
      },
      "gcp": {
        "workload_identity_provider": "<string>",
        "service_account_email": "<string>",
        "subject_scope": "<string>"
      }
    },
    "mounts": [
      {
        "id": "<string>",
        "mount_path": "<string>",
        "s3": {
          "bucket": "<string>",
          "region": "<string>",
          "endpoint_url": "<string>",
          "path_style": true,
          "prefix": "<string>"
        },
        "type": "s3",
        "cache": {
          "max_size_bytes": 1,
          "writeback_seconds": 1
        },
        "encryption": {
          "kms_key": "<string>"
        },
        "read_only": true,
        "azure_blob": {
          "container": "<string>",
          "storage_account": "<string>",
          "prefix": "<string>"
        },
        "contexthub": {
          "repo": "<string>",
          "initial_pull_only": true
        },
        "gcs": {
          "bucket": "<string>",
          "prefix": "<string>"
        },
        "git": {
          "remote_url": "<string>",
          "ref": {
            "name": "<string>",
            "type": "branch"
          },
          "refresh_interval_seconds": 2
        }
      }
    ]
  },
  "name": "<string>",
  "persistent": true,
  "preserve_memory_on_stop": true,
  "proxy_config": {
    "access_control": {
      "allow_list": [
        "<string>"
      ],
      "deny_list": [
        "<string>"
      ]
    },
    "callbacks": [
      {
        "match_hosts": [
          "<string>"
        ],
        "ttl_seconds": 1830,
        "url": "<string>",
        "full_request": true,
        "request_headers": [
          {
            "name": "<string>",
            "type": "plaintext",
            "is_set": true,
            "value": "<string>"
          }
        ]
      }
    ],
    "description": "<string>",
    "no_proxy": [
      "<string>"
    ],
    "rules": [
      {
        "name": "<string>",
        "aws": {
          "role_arn": "<string>",
          "subject_scope": "<string>"
        },
        "azure": {
          "tenant_id": "<string>",
          "client_id": "<string>",
          "subject_scope": "<string>",
          "resources": [
            "https://storage.azure.com"
          ]
        },
        "description": "<string>",
        "enabled": true,
        "env_vars": {},
        "gcp": {
          "workload_identity_provider": "<string>",
          "service_account_email": "<string>",
          "subject_scope": "<string>",
          "scopes": [
            "<string>"
          ]
        },
        "headers": [
          {
            "name": "<string>",
            "type": "plaintext",
            "is_set": true,
            "value": "<string>"
          }
        ],
        "match_headers": [
          "<string>"
        ],
        "match_hosts": [
          "<string>"
        ],
        "match_paths": [
          "<string>"
        ],
        "relay_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "rewrite": {
          "port": 32768,
          "credentials": "strip",
          "host": "<string>",
          "sandbox": "<string>"
        },
        "type": "<string>"
      }
    ]
  },
  "run_config": {
    "env_vars": {},
    "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": 123,
  "volumes": [
    {
      "mount_path": "<string>",
      "read_only": true,
      "volume_id": "<string>",
      "volume_name": "<string>"
    }
  ]
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

{
  "detail": {
    "error": "<string>",
    "error_id": "<string>",
    "message": "<string>"
  }
}

Authorizations

X-API-Key

string

header

required

Body

application/json

access_delegation

object

AccessDelegation lets code inside the sandbox call the LangSmith API as you, with at most the permissions granted here. Omit for no access.

Show child attributes

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

Show child attributes

fs_capacity_bytes

integer

Disk for the sandbox, in bytes; defaults to the snapshot's and cannot be smaller. A sandbox with persistent=false gets at most 16 GiB of disk per vCPU, so at most 256 GiB: omit CPU and it is derived from the disk, set it and a larger disk is rejected.

idle_ttl_seconds

integer

Required range: 0 <= x <= 2147483640

labels

object

Labels are free-form key/value metadata persisted with the sandbox and returned on reads. Labels from the source snapshot are inherited unless overridden here.

Show child attributes

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

object

Show child attributes

name

string

persistent

boolean

Persistent 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.

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

object

Show child attributes

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

object

RunConfig overrides the snapshot's run config for this sandbox: user and work_dir replace the snapshot's, env_vars merge over it. The result is what the sandbox boots with, and what a snapshot captured from it carries.

Show child attributes

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

object[]

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.

Maximum array length: 4

Show child attributes

Response

Created

access_delegation

object

AccessDelegation is the LangSmith access this sandbox was granted, absent when it has none. It is reported exactly as it was requested at create.

Show child attributes

cpu_millicores

integer

created_at

string

created_by

string

dataplane_url

string

delete_after_stop_seconds

integer

fs_capacity_bytes

integer

string

idle_ttl_seconds

integer

labels

object

Show child attributes

mem_bytes

integer

mount_config

object

Show child attributes

name

string

persistent

boolean

Persistent 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

object

Show child attributes

run_config

object

RunConfig is what the sandbox's commands run with: the user, working directory and base env beneath env_vars.

Show child attributes

size_class

string

snapshot_id

string

status

string

status_message

string

stopped_at

string

updated_at

string

updated_by

string

vcpus

integer

volumes

object[]

Volumes (beta) are the volumes attached to the sandbox, in slot order. Absent when the workspace does not have sandbox volumes enabled.

Show child attributes

SmithDB SDK migration

LangSmith REST API

Authorizations

Body

Response