Deploy

One-Click Deploy

The fastest way to get Atlas running in production.

Managed Postgres included. Only needs an API key.Neon Postgres + Firecracker sandbox. Serverless.🐳DockerDocker Compose + optional nsjail isolation.

Each button deploys from a starter repo — a standalone project with just Atlas, no monorepo. You get a working instance with demo data in under 5 minutes.

Create Your Own Project

The recommended way to deploy Atlas. Scaffold a project, connect your database, and deploy to any platform.

bun create @useatlas my-app
cd my-app

The interactive setup asks for your platform (Vercel, Railway, Docker), database, LLM provider, and API key. It generates a standalone project with the right config for your target.

Generate your semantic layer

# Profile your database and generate YAML files
bun run atlas -- init

# With LLM enrichment for richer descriptions
bun run atlas -- init --enrich

# Or start with demo data
bun run atlas -- init --demo

Deploy to Railway

1. Push to GitHub:

git init && git add -A && git commit -m "Initial commit"
gh repo create my-app --public --source=. --push

2. Create a new Railway project at railway.app
3. Add a Postgres plugin — Railway injects DATABASE_URL automatically (Atlas's internal database)
4. Click + New > GitHub Repo and select your repo. Railway detects railway.json and builds from the Dockerfile
5. Set environment variables in the Railway dashboard:

ATLAS_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ATLAS_DATASOURCE_URL=postgresql://user:pass@your-analytics-host:5432/mydb

6. Deploy — Railway builds and starts the container automatically
7. Verify at https://<your-app>.up.railway.app/api/health

Deploy to Vercel

1. Push to GitHub (same as above)
2. Import your repo in the Vercel Dashboard
3. Set environment variables:

# Option A: Vercel AI Gateway (recommended — single key, built-in observability)
ATLAS_PROVIDER=gateway
AI_GATEWAY_API_KEY=...           # Create at https://vercel.com/~/ai/api-keys

# Option B: Direct provider
ATLAS_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Required for both options
ATLAS_DATASOURCE_URL=postgresql://user:pass@host:5432/dbname
DATABASE_URL=postgresql://user:pass@host:5432/atlas
BETTER_AUTH_SECRET=...           # openssl rand -base64 32

4. Deploy — Vercel auto-detects Next.js and provisions Neon Postgres if configured
5. Verify at https://<your-app>.vercel.app/api/health

Deploy with Docker

From the examples/docker/ directory:

docker compose up

Or build and run manually from the project root:

docker build -f Dockerfile -t atlas .
docker run -p 3001:3001 \
  -e ATLAS_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e ATLAS_DATASOURCE_URL=postgresql://user:pass@host:5432/dbname \
  atlas

Verify at http://localhost:3001/api/health.

Platform Details

Railway

What you get with one-click: A Hono API container + managed Postgres + sidecar sandbox. Demo data is pre-seeded — you only need to provide an Anthropic API key.

• Railway auto-sets DATABASE_URL via the Postgres plugin
• railway.json configures Dockerfile builds, health checks, and restart policy
• The Docker HEALTHCHECK polls /api/health every 30 seconds

Troubleshooting:

• Health check fails after deploy — Railway Postgres can take 10–30s to provision. The app retries connections automatically. Wait for the next health check cycle.
• Demo data not appearing — Check deploy logs for seed-demo: messages. The seeding is idempotent and retries up to 5 times.

Vercel

What you get with one-click: A full-stack Next.js app with the Hono API embedded via a catch-all route. Neon Postgres is provisioned automatically. The explore tool uses Vercel Sandbox (Firecracker microVM) for hardware-level isolation.

• ATLAS_PROVIDER=gateway routes through Vercel's AI Gateway with usage tracking in the Vercel dashboard
• The catch-all route sets maxDuration = 300 (5 minutes) — this requires the Pro plan. Hobby plan limits maxDuration to 60 seconds, which may cause timeouts on complex multi-step queries. Set maxDuration = 60 if you're on Hobby. See Vercel plan limits
• @vercel/sandbox is auto-detected when ATLAS_RUNTIME=vercel is set or the VERCEL env var is present (set automatically on Vercel deployments)

Docker

What you get: A Docker Compose stack with the Hono API + Postgres. Optional nsjail isolation for the explore tool.

• Images are based on oven/bun (see the Dockerfile for the pinned version)
• The semantic layer (semantic/) is baked into the image at build time — rebuild if you update YAMLs
• The example Dockerfile (examples/docker/Dockerfile) defaults to INSTALL_NSJAIL=true — nsjail is included in the image by default. The production Dockerfile (deploy/api/Dockerfile) defaults to INSTALL_NSJAIL=false since the production deployment uses a sidecar sandbox instead. Override with --build-arg INSTALL_NSJAIL=false (or =true) as needed

For development workflows where you're iterating on the semantic layer, mount it as a volume instead of baking it into the image:

docker run -v ./semantic:/app/semantic -p 3001:3001 ... atlas

This avoids rebuilding the image on every YAML change.

Environment Variables

Every deployment needs these:

Optional (safe defaults):

See Environment Variables for the full list.

Authentication

Auth is opt-in. Set one variable to enable:

See Authentication for detailed configuration.

Security & Isolation

Atlas auto-detects the best available sandbox for the explore tool, using a six-tier priority:

Deploying for your own team? Any tier is fine — you're protecting against prompt injection edge cases, not hostile tenants. Multi-tenant? Use Vercel or nsjail for real process isolation.

See Sandbox Architecture for the full threat model.

Health Check

All deployments expose a health endpoint:

GET /api/health

Returns {"status":"ok"}, {"status":"degraded"}, or {"status":"error"} with sub-checks for datasource, provider, semantic layer, internal DB, explore (sandbox backend), auth, and slack. Returns HTTP 200 for ok/degraded, HTTP 503 for error. Always public (no auth required).