Sandboxes - Lightdash

What sandboxes are for

Some Lightdash features use an AI agent (Claude Code) that writes and runs code on your behalf. Today that’s:

AI writeback — the agent edits your dbt project (e.g. adds a metric or dimension), runs lightdash compile to validate it, and opens a pull request.
Data app generation — the agent generates and builds a small web app from a prompt.

Running model-generated code directly on the Lightdash server would be unsafe: the code is untrusted, can run arbitrary commands, and needs its own toolchain (git, dbt, the Lightdash CLI, Node). Lightdash instead runs each agent inside a sandbox — an isolated, disposable environment with a constrained network. The agent does its work there, Lightdash collects the result (a PR, a built app), and the sandbox is torn down. Sandboxes are also what make these features fast and multi-turn: a sandbox can be suspended between turns and resumed later, so a conversation with the agent keeps its state without holding a container open the whole time. Sandboxes also run Python execution , which runs Python over query results in a one-off sandbox. See Python execution.

Sandbox providers

The sandbox backend is pluggable. Lightdash talks to a provider-neutral interface, so the same feature code runs on whichever backend your deployment is configured for. You select the provider with the SANDBOX_PROVIDER environment variable.

Provider	`SANDBOX_PROVIDER`	Use for	Isolation
E2B (default)	`e2b`	Production / managed	microVM
AWS Lambda MicroVMs	`lambda-microvm`	Production on AWS (self-hosted)	microVM
Azure Container Apps Sandboxes	`azure-sandboxes`	Production on Azure (self-hosted)	microVM
Google Cloud Run Sandboxes	`gcp-cloud-run`	GCP (self-hosted, preview)	gVisor
Local Docker	`docker`	Local development only	container

E2B, AWS Lambda MicroVMs, and Azure Container Apps Sandboxes are all supported production backends. E2B is the managed default; the AWS and Azure providers are for teams who want sandboxes to run inside their own cloud account. More providers (Kubernetes, ECS) are planned.

The local Docker provider is for development only. It launches plain Docker containers via the Docker socket, which is root-equivalent on the host and provides no real isolation between the sandbox and your machine. It refuses to start when NODE_ENV=production. Do not use it for a production deployment.

LLM gateway egress

Data apps can route Claude or Codex model traffic through a corporate LLM gateway. The sandbox connects to that gateway independently from the Lightdash backend, so both network paths must be allowed.

E2B and Azure Sandboxes receive the coding agent’s effective gateway hostname in their per-sandbox egress allowlist, including any applicable Data app gateway override.
AWS Lambda MicroVMs cannot apply Lightdash’s per-sandbox allowlist. If you use a restricted LAMBDA_MICROVM_EGRESS_CONNECTOR_ARN, configure that connector to permit the gateway hostname.
Docker and Google Cloud Run use their existing runtime network path. Make sure its DNS and firewall policy can reach the gateway.

Existing E2B sandboxes keep the firewall rules from their creation when resumed. A changed gateway hostname requires a fresh sandbox or an update to the existing sandbox’s network policy; restarting Lightdash alone does not refresh those rules. These settings affect Data app coding agents, not AI writeback. If AI writeback is enabled, its sandbox still needs its existing Anthropic and git-host egress. See Corporate LLM gateways for provider configuration and the required API paths.

E2B (production default)

E2B runs each sandbox as a Firecracker microVM in E2B’s cloud. It’s the default — if you don’t set SANDBOX_PROVIDER, Lightdash uses E2B. To use it you need an E2B account and API key, and the agent needs an Anthropic API key:

SANDBOX_PROVIDER=e2b            # default, can be omitted
E2B_API_KEY=e2b_...            # from your E2B dashboard
ANTHROPIC_API_KEY=sk-ant-...   # the agent (Claude Code) runs inside the sandbox

The sandbox images are E2B templates. Lightdash uses separate templates for data apps and for AI writeback so they can be pinned or rolled back independently. These default to the published Lightdash templates and rarely need to be set:

E2B_TEMPLATE_NAME=lightdash/lightdash-data-app
E2B_TEMPLATE_TAG=<lightdash-version>             # defaults to your Lightdash version
E2B_AI_WRITEBACK_TEMPLATE_NAME=lightdash/lightdash-ai-writeback
E2B_AI_WRITEBACK_TEMPLATE_TAG=<lightdash-version>
E2B_PYTHON_TEMPLATE_NAME=lightdash-python-runner  # Python execution
E2B_PYTHON_TEMPLATE_TAG=<lightdash-version>

AWS Lambda MicroVMs (self-hosted production)

AWS Lambda MicroVMs run each sandbox as a Firecracker microVM inside your own AWS account, so untrusted agent code and your repository contents never leave your infrastructure. The microVMs have no public IP — your backend reaches each one through an AWS-managed endpoint that requires a short-lived per-microVM token — and you control their outbound network access (see Networking and IAM). This is the recommended sandbox provider for customers deploying Lightdash on AWS — it keeps the sandbox boundary inside your existing AWS account and avoids sending agent workloads or repository contents to a third-party service. Lightdash only needs the image ARN that AWS’s create-microvm-image returns. The backend passes it to RunMicrovm and never builds, pulls, or otherwise touches ECR or S3 at runtime, so any pipeline that produces a codeArtifact zip AWS can build into a MicroVM image works, with or without ECR.

Prerequisites

Provision these with your own IaC, in the region you set as LAMBDA_MICROVM_REGION and in the AWS account your backend’s credentials belong to. That’s usually the account your Lightdash backend already runs in. The backend uses the standard AWS SDK credential chain, so the resources can sit in a separate account when the backend’s role is in that account, for example an IRSA role there that trusts your cluster’s OIDC provider:

Two MicroVM images — one for data app generation and one for AI writeback (they bundle different toolchains), built from the Dockerfiles in the Lightdash repo (sandboxes/data-apps/, sandboxes/ai-writeback/) and registered as a Lambda MicroVM image on the AWS-managed al2023 base — ARM_64, 4 GB memory, with the agent’s /ready hook on port 8080. Each registration returns an image ARN for the config below. The recommended way to produce and refresh these ARNs is sandboxes/microvm-agent/build-microvm-image.sh in the Lightdash repo, which runs the whole pipeline: it builds the local Docker image for the feature you pass it (data-app or writeback), provisions the ECR repository, build IAM role, and S3 staging bucket if they don’t exist yet, and pushes the local image to ECR so the registered image can build FROM it. It then assembles a thin FROM <ecr-image> Dockerfile that adds the exec agent (sandboxes/microvm-agent/), zips it, and uploads it to S3 as the build’s codeArtifact — that zip is a thin wrapper around the ECR image, not the full application. It calls AWS’s create-microvm-image (or update-microvm-image when the image already exists), polls the build to an active version, and prints the image ARN to set as LAMBDA_MICROVM_DATA_APP_IMAGE_ARN or LAMBDA_MICROVM_AI_WRITEBACK_IMAGE_ARN. Run it with ./sandboxes/microvm-agent/build-microvm-image.sh data-app and ./sandboxes/microvm-agent/build-microvm-image.sh writeback. Pushing to ECR is the script’s shortcut to avoid rebuilding the toolchain on every update, not something Lightdash requires. The data app Dockerfile copies lightdash-query-sdk.tgz, a generated artifact that a fresh checkout does not contain. build-microvm-image.sh packs it for you; building the Dockerfile directly instead needs ./sandboxes/data-apps/pack-query-sdk.sh first, using the toolchain listed in Build the gateway image under the Cloud Run provider. The writeback Dockerfile has no such prerequisite.
Control-plane permissions on your backend’s existing IAM role — add RunMicrovm, GetMicrovm, SuspendMicrovm, ResumeMicrovm, TerminateMicrovm, CreateMicrovmAuthToken, and lambda:PassNetworkConnector (the backend attaches the ingress and egress connectors on every launch). If you set an execution role (see Networking and IAM), also allow iam:PassRole on that role’s ARN. Don’t add an iam:PassedToService condition: microVMs receive the role through a different service principal than lambda.amazonaws.com, so the condition denies the pass.

Registering an image uses AWS’s create-microvm-image, which needs a build role (trusting lambda.amazonaws.com) and an S3 location to stage the build context. These are build-time only — not the S3 bucket Lightdash already uses for results and snapshots, and the backend never touches them at runtime.

Configure the provider

SANDBOX_PROVIDER=lambda-microvm
ANTHROPIC_API_KEY=sk-ant-...   # the agent (Claude Code) runs inside the microVM

# Region the microVMs run in (defaults to eu-west-1, the EU launch region)
LAMBDA_MICROVM_REGION=eu-west-1

# The image ARNs from registering the two MicroVM images above. Required.
LAMBDA_MICROVM_DATA_APP_IMAGE_ARN=arn:aws:lambda:<region>:<account>:microvm-image/...
LAMBDA_MICROVM_AI_WRITEBACK_IMAGE_ARN=arn:aws:lambda:<region>:<account>:microvm-image/...

The backend uses its ambient AWS credentials (instance role / IRSA / standard SDK credential chain) to call the Lambda MicroVMs control plane, so no access keys are configured here.

Networking and IAM

Configure the network connectors before going to production. The AWS-managed defaults give the microVM open inbound and outbound access, which means untrusted agent code can reach the public internet from inside your AWS account. We currently recommend pointing the egress connector at a VPC connector that has no outbound access by default, and only opening up the destinations the agent actually needs (your dbt repository host, the Anthropic / Bedrock API, your ECR registry).

Override these to tighten the network boundary or to give the microVM an IAM role:

# IAM role the microVM assumes (e.g. to pull from a private ECR or reach AWS APIs)
LAMBDA_MICROVM_EXECUTION_ROLE_ARN=arn:aws:iam::...:role/lightdash-sandbox

# Network connectors. Default to AWS-managed open ingress/egress; point these at
# your own VPC connectors to constrain traffic. We strongly recommend an egress
# connector that denies outbound traffic by default.
LAMBDA_MICROVM_INGRESS_CONNECTOR_ARN=arn:aws:lambda:<region>:aws:network-connector:aws-network-connector:ALL_INGRESS
LAMBDA_MICROVM_EGRESS_CONNECTOR_ARN=arn:aws:lambda:<region>:aws:network-connector:aws-network-connector:INTERNET_EGRESS

The execution role trusts lambda.amazonaws.com with sts:AssumeRole and sts:TagSession. The sandbox reaches the internet through the egress connector rather than AWS APIs, so the role only needs CloudWatch Logs (logs:CreateLogGroup, logs:CreateLogStream, logs:PutLogEvents). Keep it separate from your backend’s role, since the sandbox runs agent-written code with whatever the execution role allows. The microVM doesn’t inherit your backend’s AWS credentials. For data apps on Bedrock, Lightdash passes BEDROCK_API_KEY or BEDROCK_ACCESS_KEY_ID and BEDROCK_SECRET_ACCESS_KEY into the sandbox; with BEDROCK_USE_DEFAULT_CREDENTIALS=true it passes none.

Upgrading

The sandbox runs whatever image LAMBDA_MICROVM_DATA_APP_IMAGE_ARN and LAMBDA_MICROVM_AI_WRITEBACK_IMAGE_ARN point to, so upgrading Lightdash alone doesn’t change what runs inside it. Fixes to either image (Dockerfile changes, the exec agent in sandboxes/microvm-agent/) only take effect once you rebuild the image:

From a checkout of the new Lightdash version, remove the local sandbox image (lightdash-sandbox:local or lightdash-ai-writeback:local). The build script reuses an existing local image instead of rebuilding it.
Run ./sandboxes/microvm-agent/build-microvm-image.sh <data-app|writeback>. It pushes the image to ECR, registers a new version of the Lambda MicroVM image, and marks it active.
If the script prints a different image ARN from the one you have configured, update LAMBDA_MICROVM_DATA_APP_IMAGE_ARN or LAMBDA_MICROVM_AI_WRITEBACK_IMAGE_ARN and restart the backend.

Azure Container Apps Sandboxes (self-hosted production)

Azure Container Apps Sandboxes run each sandbox as an isolated, microVM-class environment inside your own Azure subscription, so untrusted agent code and your repository contents never leave your infrastructure. Sandboxes have native suspend/resume (a full memory + disk snapshot with sub-second restore), which is what keeps multi-turn agent conversations fast. This is the recommended sandbox provider for customers deploying Lightdash on Azure — it keeps the sandbox boundary inside your existing Azure tenant and avoids sending agent workloads or repository contents to a third-party service.

Azure Container Apps Sandboxes is currently an Azure preview feature. It requires a Microsoft Entra ID account (personal Microsoft accounts aren’t supported), and its API surface may change while in preview.

Prerequisites

Provision these in the same Azure subscription and region your Lightdash backend runs in, using the aca CLI or the Sandboxes portal:

A sandbox group per feature — one for data app generation and one for AI writeback (they bundle different toolchains), plus an optional third for Python execution. A sandbox group (Microsoft.App/SandboxGroups) is the management boundary that holds a feature’s sandboxes and disk image. Give each group a Memory-mode auto-suspend lifecycle policy so idle sandboxes snapshot and scale to zero.
A disk image per group — build the two images from the Dockerfiles in the Lightdash repo (sandboxes/data-apps/, sandboxes/ai-writeback/), push them to a container registry (e.g. Azure Container Registry), and register each as a disk image in its sandbox group. Registration returns a disk image ID for the config below. (Unlike the AWS provider, there is no in-VM agent to build — Sandboxes expose a native command/file API.) The data app Dockerfile copies lightdash-query-sdk.tgz, a generated artifact that a fresh checkout does not contain — build and pack it into sandboxes/data-apps/ first with ./sandboxes/data-apps/pack-query-sdk.sh, using the toolchain listed in Build the gateway image under the Cloud Run provider. The writeback Dockerfile has no such prerequisite. For Python execution, build a third image from sandboxes/python-runner/, which needs a Dockerfile.local derived first — see Make sure the Python sandbox exists.
A workload identity with the data-plane role — grant your backend’s managed identity the Container Apps SandboxGroup Data Owner role on each sandbox group. Lightdash uses DefaultAzureCredential (workload identity on AKS, or the standard Azure credential chain) to authenticate — no client secret is configured here.

Configure the provider

SANDBOX_PROVIDER=azure-sandboxes
ANTHROPIC_API_KEY=sk-ant-...   # the agent (Claude Code) runs inside the sandbox

# Where your sandbox groups live
AZURE_SANDBOXES_SUBSCRIPTION_ID=<subscription-id>
AZURE_SANDBOXES_RESOURCE_GROUP=<resource-group>
AZURE_SANDBOXES_REGION=eastus2

# Per-feature sandbox group + disk image ID (from the prerequisites above). Required.
AZURE_SANDBOXES_DATA_APP_GROUP=lightdash-data-app
AZURE_SANDBOXES_DATA_APP_DISK_IMAGE=<data-app-disk-image-id>
AZURE_SANDBOXES_AI_WRITEBACK_GROUP=lightdash-writeback
AZURE_SANDBOXES_AI_WRITEBACK_DISK_IMAGE=<writeback-disk-image-id>

# Python execution only — sandbox group + disk image ID for Python sandboxes
AZURE_SANDBOXES_PYTHON_GROUP=lightdash-python
AZURE_SANDBOXES_PYTHON_DISK_IMAGE=<python-disk-image-id>

# Optional — sandbox size (XS/S/M/L, default M)
AZURE_SANDBOXES_RESOURCE_TIER=M

Egress is locked down automatically: each sandbox launches with a default-deny egress policy that only allows the hosts the agent needs (the Anthropic API and your git host), with full traffic inspection so the platform enforces the deny on all traffic and blocks non-HTTP egress. Untrusted agent code can’t reach any other destination — outbound requests to non-allowlisted hosts are rejected, and all other ports are blocked.

Google Cloud Run Sandboxes (self-hosted, preview)

Use the gcp-cloud-run provider to run data app and Python execution sandboxes in a Cloud Run service. Lightdash connects to the service through an HTTP gateway included in the sandbox image.

Cloud Run Sandboxes is in public preview and currently supports data app generation and Python execution. AI writeback is not supported.

Each gateway service runs a single toolchain image, so data apps and Python execution use separate Cloud Run services. Steps 1–5 set up the data app gateway. To run Python execution, also deploy the Python gateway.

Prerequisites

A Google Cloud project with billing enabled.
A recent version of the gcloud CLI that supports gcloud beta run deploy --sandbox-launcher.
External object storage configured for Lightdash.
An Anthropic API key.

1. Enable the Google Cloud APIs

Enable Cloud Run, plus Artifact Registry if you push the gateway image there:

gcloud services enable run.googleapis.com artifactregistry.googleapis.com \
  --project <your-project>

2. Build the gateway image

Build the gateway image from a checkout of the Lightdash repository and push it to your own registry, such as Artifact Registry. To skip the build, you can get the published image from Docker Hub instead. You need:

A checkout of the Lightdash repository at the version you deploy.
The Node version in .nvmrc and the pnpm version in the root package.json.
Repository dependencies installed with sfw pnpm install --frozen-lockfile from the repository root.
Docker with Buildx running.

From the repository root, build and push the image:

TARGET=<region>-docker.pkg.dev/<your-project>/<repo>/lightdash-sandbox-gateway:<lightdash-version>

gcloud auth configure-docker <region>-docker.pkg.dev

./sandboxes/data-apps/build-cloud-run-image.sh "$TARGET" --push

The script builds and packs the query SDK from your checkout, includes the pinned ComputeSDK gateway, and keeps /app owned by root, as Cloud Run requires.

Or get the image from Docker Hub

Every Lightdash release from 2.362.0 onward publishes a prebuilt Cloud Run gateway image to Docker Hub:

lightdash/lightdash-data-app-sandbox-cloud-run:<lightdash-version>

The image is public, so you can pull it without a Docker Hub account. It is built for linux/amd64 only. It contains:

The ComputeSDK Cloud Run gateway. The default command is node /gateway/gateway.mjs.
The data app template in /app, with its dependencies preinstalled. /app is already owned by root, as Cloud Run requires.
The @lightdash/query-sdk version that matches the release.
Node, pnpm, and the coding agents used for generation.

Use the tag that matches the Lightdash version running on your backend and scheduler. The rolling :latest tag tracks the newest release.

Images exist for Lightdash 2.362.0 and later only. For an earlier version, upgrade Lightdash or build the image yourself.

We recommend copying the image into your own registry, such as Artifact Registry, so you can scan and approve it before deploying. For example:

VERSION=<lightdash-version>
TARGET=<region>-docker.pkg.dev/<your-project>/<repo>/lightdash-data-app-sandbox-cloud-run:$VERSION

gcloud auth configure-docker <region>-docker.pkg.dev

docker pull --platform linux/amd64 \
  lightdash/lightdash-data-app-sandbox-cloud-run:$VERSION
docker tag lightdash/lightdash-data-app-sandbox-cloud-run:$VERSION "$TARGET"
docker push "$TARGET"

Or copy it directly with crane:

crane copy lightdash/lightdash-data-app-sandbox-cloud-run:$VERSION "$TARGET"

The image is published with SBOM and provenance attestations. Inspect them with:

docker buildx imagetools inspect lightdash/lightdash-data-app-sandbox-cloud-run:$VERSION

Get the image digest

Whichever option you use, get the digest of the image in your registry so you can deploy by digest:

gcloud artifacts docker images describe "$TARGET" \
  --format='value(image_summary.digest)'

3. Deploy the gateway

Generate a shared secret and deploy the image from your registry, ideally by digest:

SANDBOX_SECRET=$(openssl rand -hex 32)

gcloud beta run deploy lightdash-sandbox-gateway \
  --image <region>-docker.pkg.dev/<your-project>/<repo>/<image>@sha256:<digest> \
  --region <region> \
  --project <your-project> \
  --sandbox-launcher \
  --no-cpu-throttling \
  --session-affinity \
  --cpu 4 \
  --memory 16Gi \
  --concurrency 20 \
  --min-instances 1 \
  --max-instances 1 \
  --timeout 3600 \
  --allow-unauthenticated \
  --set-env-vars "SANDBOX_SECRET=$SANDBOX_SECRET"

Save SANDBOX_SECRET securely. You need the same value when configuring Lightdash. Although the Cloud Run service allows unauthenticated requests, the gateway rejects any sandbox operation that doesn’t include this secret. Keep the service at one instance. Active sandboxes run inside that instance and are lost if Cloud Run replaces it during a generation.

4. Configure Lightdash

Get the gateway URL:

gcloud run services describe lightdash-sandbox-gateway \
  --region <region> \
  --project <your-project> \
  --format='value(status.url)'

Set these environment variables on both the Lightdash backend and scheduler:

SANDBOX_PROVIDER=gcp-cloud-run
ANTHROPIC_API_KEY=sk-ant-...
GCP_CLOUD_RUN_SANDBOX_URL=<gateway-url>
GCP_CLOUD_RUN_SANDBOX_SECRET=<sandbox-secret>

Restart the backend and scheduler to apply the configuration.

Cloud Run sandboxes block all outbound traffic by default, but sandboxes that need internet access (data app generation does) are launched with egress fully open — the sandbox layer is on/off only, with no per-host rules. To constrain what sandboxes can reach, route the service through your VPC and filter there (next step).

5. Restrict sandbox egress (recommended)

Sandbox traffic exits through the gateway instance’s network path, so it follows the service’s VPC egress setting and can be filtered with standard VPC networking. None of this is provisioned by Lightdash — you configure it yourself:

A subnet on the VPC network you’ll filter, in the same region as the gateway service.

A Cloud Router and Cloud NAT on that network. Once the service routes all traffic through the VPC, outbound internet access only works via NAT — without it, sandboxes and the gateway itself lose all egress. Reserve a static IP for the NAT if you want a stable egress IP to allowlist on your side (for example, on your git host):

gcloud compute routers create sandbox-egress-router \
  --network <network> --region <region> --project <your-project>

gcloud compute routers nats create sandbox-egress-nat \
  --router sandbox-egress-router --region <region> --project <your-project> \
  --auto-allocate-nat-external-ips --nat-all-subnet-ip-ranges

Direct VPC egress on the gateway service. This deploys a new revision, so any active sandboxes are lost — do it while no generation is running:
gcloud beta run services update lightdash-sandbox-gateway \ --region <region> --project <your-project> \ --network <network> --subnet <subnet> --vpc-egress all-traffic
All sandbox traffic now leaves through your VPC: its public egress IP is the NAT IP, and VPC firewall egress rules apply to it — a deny rule for a destination range blocks matching sandbox traffic while the rest keeps flowing.
Filter what sandboxes can reach. VPC firewall rules give you IP/CIDR-level control. For a domain-level allowlist, add Secure Web Proxy: create a deny-all-egress firewall rule that only allows traffic to the proxy, and allowlist the domains the sandboxes and the gateway need — at minimum api.anthropic.com and your object storage endpoint. Standard data app generation and builds don’t download npm packages. Allow registry.npmjs.org, or the hosts in LIGHTDASH_APP_DEPENDENCY_REGISTRY_HOSTS, only if your data apps use custom npm dependencies, which install at build time. Secure Web Proxy is an explicit proxy: clients must be configured to use it (bake proxy settings into the gateway image — sandboxes share its root filesystem), and the deny-all firewall drops anything that bypasses it.

6. Deploy the Python gateway (optional)

Python execution needs its own gateway service, built from the Python runner image. Get the image in one of two ways:

Docker Hub — every release publishes lightdash/lightdash-python-sandbox-cloud-run:<lightdash-version> (linux/amd64 only; :latest tracks the newest release).

Build it from a checkout of the Lightdash repository at the version you deploy. This needs only Docker with Buildx and npm — no pnpm install:

TARGET=<region>-docker.pkg.dev/<your-project>/<repo>/lightdash-python-sandbox-cloud-run:<lightdash-version>

./sandboxes/python-runner/build-cloud-run-image.sh "$TARGET" --push

As with the data app image, copy it into your own registry and get its digest. Then deploy it as a second service with a different secret from the data app gateway:

PYTHON_SANDBOX_SECRET=$(openssl rand -hex 32)

gcloud beta run deploy lightdash-python-sandbox-gateway \
  --image <region>-docker.pkg.dev/<your-project>/<repo>/<image>@sha256:<digest> \
  --region <region> \
  --project <your-project> \
  --sandbox-launcher \
  --no-cpu-throttling \
  --session-affinity \
  --cpu 2 \
  --memory 4Gi \
  --concurrency 20 \
  --min-instances 1 \
  --max-instances 1 \
  --timeout 3600 \
  --allow-unauthenticated \
  --set-env-vars "SANDBOX_SECRET=$PYTHON_SANDBOX_SECRET"

Get its URL with gcloud run services describe lightdash-python-sandbox-gateway ... as in step 4, and set these on both the backend and scheduler (alongside SANDBOX_PROVIDER=gcp-cloud-run):

GCP_CLOUD_RUN_PYTHON_SANDBOX_URL=<python-gateway-url>
GCP_CLOUD_RUN_PYTHON_SANDBOX_SECRET=<python-sandbox-secret>

The Python gateway doesn’t need an Anthropic API key. Python sandboxes launch with egress denied, and the image preinstalls pandas, numpy, scipy, pyarrow, scikit-learn, and polars — there is no pip install at runtime. Then turn Python execution on. Each feature only needs its own gateway: with only the Python variables set, Python execution works and data app generation fails with a configuration error, and vice versa.

Upgrading

When you upgrade Lightdash, redeploy each gateway (data app and, if deployed, Python) with the image for the new version. Rebuild from a checkout of the new version, or copy the new version’s tag from Docker Hub. Then get its digest and rerun the deploy command from step 3 (and step 6 for the Python gateway). Cloud Run always runs the deployed gateway image. It ignores E2B_TEMPLATE_TAG, so upgrading Lightdash alone doesn’t change what runs in the sandbox. Redeploying replaces the single gateway instance, so active sandboxes are lost. Upgrade during a quiet period. To roll back, redeploy the previous version’s tag or digest.

Local Docker provider (development)

For local development you can run sandboxes as plain Docker containers on your own machine — no E2B account required. This is the recommended way to work on or try the AI features locally. It uses the same images E2B builds, but as plain local Docker images. Each feature uses a separate image (different toolchains), mirroring the E2B templates:

Image (default tag)	Built from	Used by
`lightdash-sandbox:local`	`sandboxes/data-apps/`	Data app generation
`lightdash-ai-writeback:local`	`sandboxes/ai-writeback/`	AI writeback
`lightdash-python-runner:local`	`sandboxes/python-runner/`	Python execution

Prerequisites

Docker running locally, with the daemon reachable from the Lightdash backend.
S3-compatible object storage configured (locally this is MinIO). Suspended-sandbox snapshots are tarred to object storage so a conversation survives the container being destroyed — see external object storage.
An Anthropic API key (ANTHROPIC_API_KEY) for the agent.

Setup

Build the local sandbox images (each builds from sandboxes/<feature>/):

./sandboxes/data-apps/build-local-image.sh        # -> lightdash-sandbox:local
./sandboxes/ai-writeback/build-local-image.sh     # -> lightdash-ai-writeback:local
./sandboxes/python-runner/build-local-image.sh    # -> lightdash-python-runner:local

Build only the images for the features you use. These are large (the writeback image bundles dbt, the Lightdash CLI and Claude Code) and only need rebuilding when the sandbox toolchain changes.

Point Lightdash at the Docker provider:

SANDBOX_PROVIDER=docker
# optional — these are the defaults:
SANDBOX_DOCKER_IMAGE=lightdash-sandbox:local
SANDBOX_AI_WRITEBACK_DOCKER_IMAGE=lightdash-ai-writeback:local
SANDBOX_PYTHON_DOCKER_IMAGE=lightdash-python-runner:local

Restart the backend and the scheduler so both pick up the new environment. Data app generation runs in the scheduler worker, so a stale SANDBOX_PROVIDER there will keep it on E2B. (With PM2, a plain restart reuses the cached env — delete and re-start the processes, or restart with --update-env, to actually reload the env file.)

Python execution

Python execution runs Python over the results of other queries in a pipeline. Lightdash writes the referenced results into a fresh sandbox, runs the code, reads the output back, and destroys the sandbox. The sandbox has no credentials and no outbound network access. Lightdash never suspends it, so snapshot lifecycle settings don’t apply. The sandbox image includes pandas, numpy, scipy, pyarrow, scikit-learn, and polars. Your code must return a pandas DataFrame.

Supported providers

Python execution runs on the E2B, Azure Container Apps Sandboxes, Google Cloud Run, and Local Docker providers. It doesn’t work on lambda-microvm.

Make sure the Python sandbox exists

E2B — Lightdash launches E2B_PYTHON_TEMPLATE_NAME (default lightdash-python-runner) at E2B_PYTHON_TEMPLATE_TAG (default: your Lightdash version). Your E2B_API_KEY must have access to the template at that tag. To build the template in your own E2B team, check out the Lightdash repository at your version, run the build from sandboxes/python-runner/, and then set both variables to the template you built:
cd sandboxes/python-runner pnpm install E2B_API_KEY=e2b_... E2B_PYTHON_TEMPLATE_TAG=<lightdash-version> pnpm run build
When you upgrade Lightdash, rebuild or retag the template so a build exists at the new version’s tag, or pin E2B_PYTHON_TEMPLATE_TAG.
Google Cloud Run — deploy the separate Python gateway and set GCP_CLOUD_RUN_PYTHON_SANDBOX_URL and GCP_CLOUD_RUN_PYTHON_SANDBOX_SECRET. See Deploy the Python gateway.
Azure Container Apps Sandboxes — build the image from sandboxes/python-runner/ and register it as a disk image in a dedicated Python sandbox group. The directory ships an E2B Dockerfile, so first derive Dockerfile.local from it with ./sandboxes/python-runner/build-local-image.sh (you can ignore the local image it then builds). Azure sandboxes run on linux/amd64, so build for that platform and register the result:
az acr build --registry <acr> --platform linux/amd64 \ --image lightdash-python-runner:<lightdash-version> \ --file sandboxes/python-runner/Dockerfile.local sandboxes/python-runner aca sandboxgroup disk create --group <python-group> --region <region> \ --image <acr>.azurecr.io/lightdash-python-runner:<lightdash-version> \ --username 00000000-0000-0000-0000-000000000000 \ --token "$(az acr login --name <acr> --expose-token --query accessToken -o tsv)" aca sandboxgroup disk list --group <python-group> --region <region> -o json
Set AZURE_SANDBOXES_PYTHON_GROUP to the group and AZURE_SANDBOXES_PYTHON_DISK_IMAGE to the disk image ID from disk list, and grant the backend identity the same data-plane role on the group. See Azure Container Apps Sandboxes.
Local Docker — build lightdash-python-runner:local with ./sandboxes/python-runner/build-local-image.sh, or set SANDBOX_PYTHON_DOCKER_IMAGE to your own tag. See Local Docker provider.

Turn it on

Python execution is part of the composer, gated by the compose-sql-runner feature flag, which is off by default. To turn it on, set LIGHTDASH_ENABLE_FEATURE_FLAGS on the backend and the scheduler:

LIGHTDASH_ENABLE_FEATURE_FLAGS=compose-sql-runner

Snapshot lifecycle

Every turn suspends its own sandbox, so in steady state nothing sits idle. Two timers configure the cloud-side idle policy as a backstop — when to auto-suspend a sandbox left running and when to auto-terminate a suspended one:

SANDBOX_IDLE_TIMEOUT_MS=1800000        # auto-suspend a running-but-idle sandbox (default 30 min)
SANDBOX_SNAPSHOT_RETENTION_MS=604800000 # auto-terminate a suspended microVM (default 7 days); also how long a thread stays resumable

SANDBOX_IDLE_TIMEOUT_MS feeds the auto-suspend policy on both the Lambda MicroVMs and Azure Sandboxes providers (for Azure it sets each sandbox’s Memory-mode auto-suspend interval). SANDBOX_SNAPSHOT_RETENTION_MS is read only by Lambda MicroVMs — on Azure, suspended-sandbox retention is governed by the sandbox group’s own auto-delete policy. E2B manages idle sandboxes itself, and the Docker and Cloud Run providers have no cloud-side idle handling — both persist suspend-time snapshots to object storage and destroy the sandbox, so nothing idles in the first place.

Environment variable reference

Variable	Default	Description
`SANDBOX_PROVIDER`	`e2b`	Sandbox backend: `e2b`, `lambda-microvm`, `azure-sandboxes`, `gcp-cloud-run`, or `docker`.
`ANTHROPIC_API_KEY`	—	API key for the Claude Code agent running inside the sandbox.
`E2B_API_KEY`	—	E2B API key (required when `SANDBOX_PROVIDER=e2b`).
`E2B_TEMPLATE_NAME`	`lightdash/lightdash-data-app`	E2B template for data app sandboxes.
`E2B_TEMPLATE_TAG`	Lightdash version	Tag of the data app template to launch.
`E2B_AI_WRITEBACK_TEMPLATE_NAME`	`lightdash/lightdash-ai-writeback`	E2B template for writeback sandboxes.
`E2B_AI_WRITEBACK_TEMPLATE_TAG`	Lightdash version	Tag of the writeback template to launch.
`E2B_PYTHON_TEMPLATE_NAME`	`lightdash-python-runner`	E2B template for Python execution sandboxes.
`E2B_PYTHON_TEMPLATE_TAG`	Lightdash version	Tag of the Python execution template to launch.
`LAMBDA_MICROVM_REGION`	`eu-west-1`	AWS region the microVMs run in (`lambda-microvm`).
`LAMBDA_MICROVM_DATA_APP_IMAGE_ARN`	—	Image ARN for data app microVMs (required when `SANDBOX_PROVIDER=lambda-microvm`).
`LAMBDA_MICROVM_AI_WRITEBACK_IMAGE_ARN`	—	Image ARN for writeback microVMs (required when `SANDBOX_PROVIDER=lambda-microvm`).
`LAMBDA_MICROVM_EXECUTION_ROLE_ARN`	—	Optional IAM role the microVM assumes.
`LAMBDA_MICROVM_INGRESS_CONNECTOR_ARN`	AWS-managed `ALL_INGRESS`	Optional ingress network connector.
`LAMBDA_MICROVM_EGRESS_CONNECTOR_ARN`	AWS-managed `INTERNET_EGRESS`	Optional egress network connector.
`AZURE_SANDBOXES_SUBSCRIPTION_ID`	—	Azure subscription holding the sandbox groups (required when `SANDBOX_PROVIDER=azure-sandboxes`).
`AZURE_SANDBOXES_RESOURCE_GROUP`	—	Resource group holding the sandbox groups (required when `azure-sandboxes`).
`AZURE_SANDBOXES_REGION`	`eastus2`	Region the sandboxes run in (selects the data-plane endpoint).
`AZURE_SANDBOXES_DATA_APP_GROUP`	—	Sandbox group for data app sandboxes (required when `azure-sandboxes`).
`AZURE_SANDBOXES_DATA_APP_DISK_IMAGE`	—	Disk image ID for data app sandboxes (required when `azure-sandboxes`).
`AZURE_SANDBOXES_AI_WRITEBACK_GROUP`	—	Sandbox group for writeback sandboxes (required when `azure-sandboxes`).
`AZURE_SANDBOXES_AI_WRITEBACK_DISK_IMAGE`	—	Disk image ID for writeback sandboxes (required when `azure-sandboxes`).
`AZURE_SANDBOXES_PYTHON_GROUP`	—	Sandbox group for Python execution sandboxes (required for Python execution when `azure-sandboxes`).
`AZURE_SANDBOXES_PYTHON_DISK_IMAGE`	—	Disk image ID for Python execution sandboxes (required for Python execution when `azure-sandboxes`).
`AZURE_SANDBOXES_RESOURCE_TIER`	`M`	Sandbox size: `XS`, `S`, `M`, or `L`.
`AZURE_SANDBOXES_API_VERSION`	`2026-02-01-preview`	Azure Sandboxes data-plane API version.
`AZURE_SANDBOXES_TOKEN_SCOPE`	`https://management.azuredevcompute.io/.default`	Entra token scope for the data plane.
`GCP_CLOUD_RUN_SANDBOX_URL`	—	URL of the data app sandbox gateway Cloud Run service (required for data apps when `SANDBOX_PROVIDER=gcp-cloud-run`).
`GCP_CLOUD_RUN_SANDBOX_SECRET`	—	Shared secret the data app gateway was deployed with (required for data apps when `gcp-cloud-run`).
`GCP_CLOUD_RUN_PYTHON_SANDBOX_URL`	—	URL of the Python sandbox gateway Cloud Run service (required for Python execution when `gcp-cloud-run`).
`GCP_CLOUD_RUN_PYTHON_SANDBOX_SECRET`	—	Shared secret the Python gateway was deployed with (required for Python execution when `gcp-cloud-run`).
`SANDBOX_DOCKER_IMAGE`	`lightdash-sandbox:local`	Local image for data app sandboxes (`docker` provider).
`SANDBOX_AI_WRITEBACK_DOCKER_IMAGE`	`lightdash-ai-writeback:local`	Local image for writeback sandboxes (`docker` provider).
`SANDBOX_PYTHON_DOCKER_IMAGE`	`lightdash-python-runner:local`	Local image for Python execution sandboxes (`docker` provider).
`SANDBOX_IDLE_TIMEOUT_MS`	`1800000` (30 min)	Auto-suspend a running-but-idle sandbox (`lambda-microvm` and `azure-sandboxes`). Ignored by `e2b`/`docker`.
`SANDBOX_SNAPSHOT_RETENTION_MS`	`604800000` (7 days)	Lambda MicroVMs idle policy: auto-terminate a suspended microVM (also how long a thread stays resumable). Ignored by `e2b`/`azure-sandboxes`/`docker`.