\
--wait
```
## Enable with Terraform
The LangSmith Terraform modules can provision the required AWS and GCP infrastructure and generate the corresponding Helm values.
In `modules/aws/infra/terraform.tfvars`, enable Sandboxes and configure the sandbox node capacity:
```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
enable_sandboxes = true
redis_source = "external"
sandbox_juicefs_redis_instance_type = "cache.m6g.large"
sandbox_juicefs_redis_snapshot_retention_limit = 7
sandbox_host_node_count = 1
sandbox_host_instance_types = ["m5d.metal"]
sandbox_host_configure_instance_store = true
sandbox_host_image_tag = ""
```
AWS Sandboxes require `redis_source = "external"`. The Terraform module:
* Creates a dedicated ElastiCache Redis instance for JuiceFS sandbox metadata.
* Configures that dedicated instance with the recommended `noeviction` policy.
* Reuses the LangSmith S3 bucket for sandbox object storage.
* Creates the JuiceFS configuration Secret.
* Adds the expected node label and taint.
The AWS setup script generates the sandbox service-auth secret, callback signing JWK, and dedicated JuiceFS Redis auth token through the normal SSM-backed setup flow. Run the infra setup script before applying Terraform if those values do not exist yet.
If you deploy the Helm release with the Terraform app module, set the sandbox app values in `modules/aws/app/terraform.tfvars` as well:
```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
enable_sandboxes = true
chart_version = "~0.17.0"
sandbox_host_image_tag = ""
```
When `enable_sandboxes = true`, the Terraform app module requires an explicit LangSmith Helm chart v17 release and a sandbox runtime image tag.
Run the normal AWS flow:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
make apply
make init-values
CHART_VERSION="~0.17.0" make deploy
```
In `modules/gcp/infra/terraform.tfvars`, enable Sandboxes and configure a Standard GKE node pool:
```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
enable_sandboxes = true
redis_source = "external"
gke_use_autopilot = false
enable_gcp_iam_module = true
sandbox_juicefs_redis_memory_size = 5
sandbox_juicefs_redis_high_availability = true
sandbox_host_node_count = 1
sandbox_host_min_node_count = 1
sandbox_host_max_node_count = 5
sandbox_host_machine_type = "n2-standard-8"
sandbox_host_image_tag = ""
```
GCP Sandboxes require `redis_source = "external"`. The Terraform module:
* Creates a dedicated Memorystore Redis instance for JuiceFS sandbox metadata.
* Configures that dedicated instance with the recommended `noeviction` policy.
* Reuses the LangSmith GCS bucket for sandbox object storage.
* Creates the JuiceFS configuration Secret.
* Adds the expected node label and taint.
The GCP setup script generates the sandbox service-auth secret and callback signing JWK through the normal Secret Manager setup flow. Run the infra setup script before applying Terraform if those values do not exist yet.
If you deploy the Helm release with the Terraform app module, set the sandbox app values in `modules/gcp/app/terraform.tfvars` as well:
```hcl theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
enable_sandboxes = true
chart_version = "~0.17.0"
sandbox_host_image_tag = ""
```
When `enable_sandboxes = true`, the Terraform app module requires an explicit LangSmith Helm chart v17 release and a sandbox runtime image tag.
Run the normal GCP flow:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
make apply
make init-values
CHART_VERSION="~0.17.0" make deploy
```
## Optional: enable service URLs
Set `sandboxes.serviceUrlBaseUrl` when users need browser or programmatic access to HTTP services running inside Sandboxes.
```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
sandboxes:
serviceUrlBaseUrl: "https://sandbox-services.example.com"
```
This requires wildcard DNS and TLS for `*.sandbox-services.example.com`. When `ingress.enabled` is `true`, the chart also adds a wildcard ingress rule that routes these service URLs to the LangSmith platform backend.
Service URLs also require an Ed25519 private JWKS with a nonempty `kid` on its first key. Set `config.signingJwks`, or add `langsmith_signing_jwks` to your [existing LangSmith app Secret](/langsmith/self-host-using-an-existing-secret). This is separate from `sandboxes.callbackSigningJwk`. For key generation instructions, see [Configure a signing JWKS](/langsmith/langsmith-remote-mcp#enabling-remote-mcp).
Service URLs are required to [build and edit custom apps with chat](/langsmith/custom-apps#configure-self-hosted-chat), even though they are optional for other sandbox workflows.
## Verify the installation
After the upgrade completes, verify that the sandbox runtime pods and JuiceFS volumes are ready:
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
kubectl rollout status deployment/sandbox-host -n
kubectl get pods,pvc -n
```
Then run a sandbox smoke test:
1. Create a sandbox from a public image, such as a Python image.
2. Start a Python HTTP server inside the sandbox.
3. Snapshot the sandbox with memory enabled.
4. Create a new sandbox from the snapshot.
5. Verify that the HTTP server is still running in the restored sandbox.
## Upgrade notes
Sandbox runtime image changes roll out through the `sandbox-host` Kubernetes Deployment. The chart uses a no-surge rolling update strategy by default, so hosts are replaced one at a time.
During a normal Helm upgrade, a terminating host stops accepting new Sandboxes, attempts to save each running Sandbox's VM memory to JuiceFS, and then stops those VMs before the pod exits. This shutdown is bounded by the `sandbox-host` pod termination grace period, which defaults to 300 seconds. This is not live migration: Sandboxes on that host are interrupted during the restart.
Sandboxes are not proactively restarted. They start again when a user or API action starts the Sandbox, or when a request path wakes it. LangSmith then places the Sandbox on an available host and restores from the saved memory image if the shutdown capture completed. If the memory image is absent or incomplete, the Sandbox starts from the saved root filesystem.
***
[Connect these docs](/use-these-docs) to your agent of choice via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/enable-self-hosted-sandboxes.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).