Quick Start

Prerequisites

• Bun v1.3.10+
• Docker -- required for local PostgreSQL (matches production setup)
• An LLM API key (Anthropic, OpenAI, or another supported provider)

Setup

git clone https://github.com/AtlasDevHQ/atlas.git
cd atlas
bun install
bun run db:up                        # Start Postgres + seed demo data

This launches a postgres:16-alpine container via Docker Compose with two databases:

• atlas -- Atlas internals (auth, audit, conversations)
• atlas_demo -- Demo analytics data (50 companies, ~200 people, 80 accounts), seeded automatically on first start

Note: db:up already seeds the simple demo data -- you do not need --demo when using it. For a larger, production-like dataset, use bun run atlas -- init --demo cybersec or bun run atlas -- init --demo ecommerce instead. See Demo Datasets for all available demos.

Configure your environment:

cp .env.example .env

Edit .env -- set your LLM provider (the database URLs are pre-configured for local Docker):

ATLAS_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

Generate the semantic layer and start:

bun run atlas -- init                # Profile DB and generate YAMLs
bun run dev                          # http://localhost:3000

Dev admin account: When using managed auth with the local Docker setup, a dev admin account is seeded automatically: admin@atlas.dev / atlas-dev.

New project scaffolding: bun create @useatlas my-app provides interactive setup with template selection, DB config, provider setup, and optional semantic layer generation.

Ask your first question

Open http://localhost:3000 in your browser. The chat UI shows suggested starter questions derived from the semantic layer. Try one of these:

• "How many companies are there by industry?"
• "What is the average revenue across all companies?"
• "Which departments have the most people?"

The agent will explore the semantic layer YAMLs, write validated SQL, execute it against your database, and return an interpreted answer.

Using your own database

To connect Atlas to your own database instead of the demo:

1. Set ATLAS_DATASOURCE_URL in .env:
   • PostgreSQL: postgresql://user:pass@host:5432/dbname
   • MySQL: mysql://user:pass@host:3306/dbname (also accepts mysql2://)
2. Generate a semantic layer from your schema:

bun run atlas -- init

To profile only specific tables:

bun run atlas -- init --tables users,orders,products

To add LLM-enriched descriptions and query patterns (requires a configured API key):

bun run atlas -- init --enrich

See CLI Reference for all init flags.

See Connect Your Data for production database setup including read-only users, SSL, and safety configuration.

Useful commands

See CLI Reference for all commands and flags.

Troubleshooting

Docker not running If bun run db:up fails, make sure Docker Desktop is running. The local Postgres container requires Docker Compose.

Port 3000 or 3001 already in use Check for other dev servers occupying those ports. Use lsof -i :3000 (or :3001) to find the process, then stop it or choose a different port.

bun run atlas -- init fails Verify that ATLAS_DATASOURCE_URL is set in your .env and that the database is reachable. Run bun run atlas -- doctor to check connectivity.

Semantic layer errors Run bun run atlas -- validate to check for YAML syntax issues, missing fields, or invalid references. This runs offline -- no database or API key required.

Next steps

• Deploy to production
• Connect your own database