Skip to main content
🛠 This page is for engineering teams self-hosting their own Lightdash instance. On Lightdash Cloud, sandboxes are fully managed for you — there’s nothing to configure.

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

​
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. More providers (Kubernetes, ECS, microVM-based) are planned, but E2B is the only supported production backend today.
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.

​
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:
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:

​
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. Two separate images are used (different toolchains), mirroring the two E2B templates:

​
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

  1. Build the local sandbox images (each builds from sandboxes/<feature>/):
    These are large (the writeback image bundles dbt, the Lightdash CLI and Claude Code) and only need rebuilding when the sandbox toolchain changes.
  2. Point Lightdash at the Docker provider:
  3. 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.)

​
Snapshot lifecycle

Two timers control how long sandboxes live:
In steady state every turn suspends its own sandbox, so the idle timeout is just a safety net for crashes. The retention window controls how long a conversation thread can be resumed before its snapshot is garbage-collected.

​
Environment variable reference