Sandbox Configuration
Configure the sandbox backend that the explore and Python tools use to execute commands safely.
The sandbox is the isolated execution environment that Atlas uses to run the explore tool (file browsing, grep, find on the semantic layer) and Python tool (data analysis scripts). The admin page lets you select which backend to use and — in SaaS mode — connect your own cloud sandbox providers.
Prerequisites
- Managed auth enabled
- A user with the
adminrole
Overview
Route: /admin/sandbox
The page adapts based on deploy mode:
- Self-hosted — A dropdown selector for backend IDs with sidecar URL configuration
- SaaS — An integration card grid where workspace admins connect their own sandbox providers
SaaS Mode — Execution Environment
In SaaS mode the page is titled Execution Environment and presents a card grid with four sandbox providers:
Atlas Cloud Sandbox
Managed container service with HTTP isolation. No credentials needed and no setup required. This is the default for all workspaces and is marked (Recommended).
- Active state — highlighted border with "Active" badge
- Inactive state — click Select to make it active
Vercel Sandbox
Firecracker microVM with network isolation. Bring your own Vercel account.
Credentials:
- Access Token — Vercel API access token
- Team ID — Vercel team identifier (e.g.
team_...)
Credentials are validated against the Vercel API before saving. The team name is displayed after connection.
E2B
Bring your own E2B account for ephemeral cloud sandboxes with sub-second startup.
Credentials:
- API Key — E2B API key
Validated against the E2B sandboxes API before saving.
Daytona
Bring your own Daytona account for cloud-hosted development sandboxes.
Credentials:
- API Key — Daytona API key
- API URL (optional) — Custom API endpoint (defaults to
https://api.daytona.io)
Validated against the Daytona health endpoint before saving.
Connect / Disconnect Flow
- Click Connect on a provider card
- Enter credentials in the dialog
- Click Validate & Connect — credentials are verified against the provider API
- On success, the card shows as Connected with the account name and connection date
- Click Select to make a connected provider the active sandbox
- Click Disconnect to remove credentials (reverts to Atlas Cloud Sandbox, the platform default, if this was the active provider)
Credentials are stored per-workspace in the sandbox_credentials table. Each workspace can connect different providers independently.
Self-Hosted Mode — Backend Selector
In self-hosted mode, the page shows the original dropdown UI:
- Platform default — The backend selected at the platform level
- Active backend — The backend currently in use
- Workspace override — A per-workspace selection, if set
Selecting a Backend
- Open
/admin/sandbox - Choose a backend from the Backend dropdown
- Click Save
To return to the platform default, select Use platform default from the dropdown, or click Reset to default.
Sidecar Configuration
When the Sidecar backend is selected, an additional Sidecar URL field appears. This is the URL of the @atlas/sandbox-sidecar service.
- Set the URL to your sidecar deployment (e.g.
http://sandbox:3002) - Leave empty to use the platform default
The sidecar is a separate service that runs explore and Python commands in an isolated container. See the Docker deployment example for a production sidecar setup.
The admin UI dropdown only shows API-enumerable backends (Vercel Sandbox, Sidecar, and plugin backends). nsjail and just-bash are resolved by the priority chain but are not selectable from the dropdown.
Available Backends
Atlas supports multiple sandbox backends. The active backend is resolved using a priority chain:
| Backend | Type | Description |
|---|---|---|
| Plugin | plugin | Custom sandbox provided by a plugin (highest priority) |
| Vercel Sandbox | built-in | Vercel's secure sandbox environment (used on Vercel deployments) |
| nsjail | built-in | Linux namespace isolation via nsjail binary |
| Sidecar | built-in | External sandbox sidecar service (@atlas/sandbox-sidecar) |
| just-bash | built-in | Direct shell execution (development fallback only) |
The just-bash backend provides no isolation and should only be used in local development. Production deployments should use Vercel Sandbox, nsjail, or the sidecar.
Priority Resolution
When no explicit override is set, Atlas auto-detects the best available backend using this default priority chain:
- Plugin backends (always highest priority)
- Vercel Sandbox (when running on Vercel)
- nsjail explicit (when
ATLAS_SANDBOX=nsjailis set) - Sidecar (when
ATLAS_SANDBOX_URLis set) - nsjail auto-detect (when nsjail binary is found on PATH)
- just-bash (development fallback)
You can override this chain with the ATLAS_SANDBOX_PRIORITY environment variable or via sandbox.priority in atlas.config.ts.
SaaS vs Self-Hosted
| Behavior | Self-Hosted | SaaS |
|---|---|---|
| Page title | Sandbox | Execution Environment |
| UI | Backend dropdown + sidecar URL | Provider card grid with connect/disconnect |
| Providers | Not applicable | Atlas Cloud, Vercel, E2B, Daytona |
| Credential storage | Not applicable | Per-workspace in sandbox_credentials table |
| Active selection | Dropdown + Save in admin UI (sets ATLAS_SANDBOX_BACKEND) | Click Select on a connected provider |
| Default fallback | Auto-detect priority chain | Atlas Cloud Sandbox (sidecar) |
| Sidecar URL | Configurable via admin UI | Managed by platform |
Environment Variables
| Variable | Description |
|---|---|
ATLAS_SANDBOX_URL | Sidecar service URL (implies sidecar backend) |
ATLAS_SANDBOX_PRIORITY | Comma-separated backend priority list |
The priority list can also be set via sandbox.priority in atlas.config.ts. The sidecar URL is configured via the ATLAS_SANDBOX_URL environment variable or the admin Settings page.
API Endpoints
All endpoints require admin authentication.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/admin/sandbox/status | Get sandbox configuration, available backends, and connected providers |
POST | /api/v1/admin/sandbox/connect/{provider} | Validate and save provider credentials (vercel, e2b, daytona) |
DELETE | /api/v1/admin/sandbox/disconnect/{provider} | Remove provider credentials |
PUT | /api/v1/admin/settings/ATLAS_SANDBOX_BACKEND | Set workspace sandbox backend |
PUT | /api/v1/admin/settings/ATLAS_SANDBOX_URL | Set workspace sidecar URL |
DELETE | /api/v1/admin/settings/ATLAS_SANDBOX_BACKEND | Reset to platform default |
See Also
- Admin Console — Overview of all admin pages
- Integrations Hub — Connect Slack, Teams, and other platforms
- Environment Variables — Full variable reference
- Docker Deployment — Sidecar setup in Docker