# Atlas documentation

> Atlas is a model-agnostic, terminal-native AI coding agent. Plan, edit, and ship from the place you already live: your shell.

Install Atlas, connect your models, organize agents and workflows, and keep control of code, context, and client data from the terminal.

## Install

```sh
curl -fsSL https://runatlas.sh/install | sh
```

## Introduction

**Atlas** is a model-agnostic, terminal-native AI coding agent for developers and teams that want control over their model routes, code context, tools, and approval flow.

Atlas is designed around four operating principles:

- **Bring your own models.** Use hosted, local, self-hosted, or approved open-source models based on the work.
- **Keep private work private.** Local embeddings, permission gates, and auditable tool calls help protect client and company code.
- **Use agents intentionally.** Atlas can plan, build, review, and coordinate multiple agents when a task is large enough.
- **Stay in the terminal.** Sessions, diffs, approvals, models, MCP tools, and copy formats are all reachable from the TUI.

## Installation

Atlas ships as a single binary. Install it, restart your shell if needed, then run `atlas --version` to confirm your PATH.

#### macOS and Linux

```bash
curl -fsSL https://runatlas.sh/install | sh
```

#### Windows PowerShell

```powershell
irm https://runatlas.sh/install.ps1 | iex
```

> **Keep devices current:** Run `atlas upgrade` on each machine. Atlas updates the local binary on that device; repository changes still move through git.

## Free account signup and sign-in

Atlas works without an account. A free account gives this installation an authenticated Atlas identity and lets Atlas read the account's effective entitlement when account features are used.

Run `atlas signup` and enter your email. Atlas sends a six-digit code: a new email creates a free account, while an existing email signs back in. No password is created or entered in the terminal.

terminal:
```bash
atlas signup

# These names open the same passwordless flow:
atlas signin
atlas login
```

> **Account remains optional:** Installation, local usage, and Atlas updates do not require sign-in. Run `atlas logout` at any time to remove the linked account from this machine.

## Quickstart

Open Atlas in a repository and describe the outcome. Atlas reads the project, chooses the right context, proposes a plan when needed, and shows work as reviewable terminal output.

terminal:
```bash
cd ~/code/your-project
atlas

> Review this API change, update the tests, and call out any risky migrations.
```

For larger work, say what you want operationally. Phrases like `use multiple agents`, `parallelize the review`, or `split this into agents` are signals that Atlas should coordinate separate discovery, implementation, and verification lanes.

> **NOTE:** For one-shot automation, use `atlas run`. For interactive work, use the TUI so you can inspect plans, approvals, sessions, and model choices as the task evolves.

## Update Atlas

Atlas has a dedicated upgrade command. Use it instead of passing update flags to the default TUI command.

terminal:
```bash
atlas upgrade
atlas --version
```

If a different machine has newer repository code, pull that repository with git and rebuild from source as needed. If you installed from the public installer, `atlas upgrade` updates the installed binary.

## Models

Atlas is model-agnostic. List available models, authenticate providers, and select the model that fits the task, budget, and data policy.

terminal:
```bash
atlas providers
atlas models
atlas models --refresh
atlas --model anthropic/claude-sonnet-4-5
```

| Item | Detail |
| --- | --- |
| Hosted provider | Use provider/model IDs after authenticating your provider. |
| Local Ollama | Use local models and embeddings when client data must stay on your machine. |
| Model picker | Switch providers, models, variants, and effort without rebuilding the project. |
| Per-run override | Pass --model provider/model when launching Atlas or atlas run. |

## Providers & API keys

Atlas brings your own keys. Set a provider's environment variable, or run `atlas providers` to authenticate interactively, and Atlas registers that provider's models automatically. A provider counts as configured as soon as any one of its environment variables is set.

The table below is providers, not models. Atlas does not maintain a model list: the catalog comes from models.dev and is refreshed with `atlas models --refresh`, so any model IDs written here would be stale within a release. Run `atlas models <provider>` for the live list.

terminal:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
atlas models anthropic
atlas --model anthropic/claude-opus-5
```

> **Do not trust a model ID you read in a blog post:** Model IDs are retired on a schedule. `claude-3-5-sonnet` and `gpt-4o` still appear in setup guides across the web and no longer resolve. `atlas models <provider>` reads the live catalog and is the only list worth copying from.

| Provider | Env variable | List models |
| --- | --- | --- |
| Anthropic | `ANTHROPIC_API_KEY` | `atlas models anthropic` |
| OpenAI | `OPENAI_API_KEY` | `atlas models openai` |
| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | `atlas models google` |
| OpenRouter | `OPENROUTER_API_KEY` | `atlas models openrouter` |
| xAI | `XAI_API_KEY` | `atlas models xai` |
| Azure OpenAI | `AZURE_OPENAI_API_KEY` | `atlas models azure` |
| Amazon Bedrock | `AWS_BEARER_TOKEN_BEDROCK` | `atlas models amazon-bedrock` |
| Cloudflare Workers AI | `CLOUDFLARE_API_TOKEN` | `atlas models cloudflare` |

Key links and local-model setup: https://runatlas.sh/models.md

## Local models

Use a local model route when client requirements or internal policies require model calls to stay on your machine or approved infrastructure. Atlas can discover Ollama and LM Studio when you explicitly run the local-model command.

terminal:
```bash
ollama list
ollama pull qwen2.5-coder:latest
atlas models --local
```

> **Data path matters:** A local model only protects data for the calls routed to that model. Keep provider keys, MCP servers, and plugins aligned with the privacy policy you promise clients.

## Agents

Agents are reusable operating modes. Use primary agents for normal work and subagents for focused research, review, migration, or testing lanes.

terminal:
```bash
atlas agent list
atlas agent create
```

Specialized agents live in Atlas configuration and can carry their own instructions, model preference, and permission profile. Keep them small and purpose-built: reviewer, migration planner, test fixer, security checker, or documentation writer.

## Workflows

Workflows turn repeated senior-engineering patterns into reusable execution paths. Use them when a task needs coordination across files, tests, reviews, or agents.

| Item | Detail |
| --- | --- |
| Single task | Ask Atlas to make a focused change, then review the plan and diff. |
| Review | Use /review for branches, uncommitted work, PR prep, and delivery checks. |
| Parallel agents | Ask Atlas to use multiple agents when discovery, migration, testing, or review can run in parallel. |
| Large codebase | Use workflows and context-aware search so Atlas can narrow the right files before editing. |

prompt examples:
```bash
Use multiple agents: one for TUI routing, one for tests, one for docs.
Run a review workflow before committing this branch.
Use a workflow to migrate this feature and verify the build.
```

## Codebase intelligence

Atlas gathers context from the repository, session history, project files, command output, and available tools. For large codebases, ask it to map the relevant area before editing.

- Use `/init` to create project guidance Atlas can read later.
- Ask for a file map before broad migrations.
- Prefer scoped prompts that name the subsystem, test, or failure.
- Use local embeddings when code search must stay private.

The resource hubs expand this further with guides for private AI development, local model orchestration, agentic workflows, and codebase intelligence. [Browse resource hubs](https://runatlas.sh/resources)

## Permissions

Atlas treats tool calls as actions that should be classified and gated. Read-only discovery, file edits, shell commands, network calls, and secret-bearing operations do not carry the same risk.

atlas.json:
```json
{
  "permission": "ask",
  "agent": {
    "default_agent": "build"
  }
}
```

> **TIP:** Use tighter permissions for client repositories and broader permissions only for trusted local maintenance tasks.

## Configuration

Atlas reads global configuration plus project-level configuration. Use project config for repository conventions and global config for personal defaults.

atlas.json:
```json
{
  "model": "ollama/qwen2.5-coder:latest",
  "theme": "atlas",
  "permission": "ask"
}
```

Environment variables and command flags can override config when you need a one-off model, session, or server mode.

## Plugins & MCP

Plugins extend Atlas directly. MCP connects Atlas to external tools and context providers through the Model Context Protocol. Both should follow the same permission discipline as built-in tools.

terminal:
```bash
atlas mcp add
atlas mcp list
atlas mcp auth <name>
atlas mcp debug <name>
```

> **WARNING:** MCP servers can expose external systems. Only add servers you trust, and keep credentials scoped to what the workflow needs.

## Sessions

Sessions keep work durable across restarts and machines when the same repository and data are available. Continue the last session, resume a known session ID, or fork a session when you want a new branch of work.

terminal:
```bash
atlas --continue
atlas --session ses_abc123
atlas --session ses_abc123 --fork
atlas session list
```

## Atlas Cloud

**Atlas Cloud** is the optional commercial control plane. The agent keeps running locally with your own model keys; Atlas Cloud adds accounts, entitlements, release manifests, device registration, sync, and allowlisted telemetry on top.

It is designed so ordinary control-plane operations never require your repo contents, prompts, diffs, terminal output, local indexes, embeddings, model outputs, provider request bodies, file paths, or credentials. The local product talks to Atlas Cloud through published API contracts only, so cloud availability never blocks your work.

| Item | Detail |
| --- | --- |
| cloud-api | Accounts, entitlements, releases, devices, sync, and telemetry intake. |
| model-router | Optional hosted model routing, provider policy, credits, and rate limits. |
| cloud-worker | Billing reconciliation, usage rollups, retention, and release validation. |

> **Cloud is opt-in:** You can run Atlas fully local with bring-your-own-keys and never touch the control plane. Cloud features activate only when you sign in or enable them.

Learn more: [the privacy-preserving control plane](https://runatlas.sh/resources/features/atlas-cloud).

## Licensing & entitlements

Atlas verifies licenses **offline** against a key built into the binary, so Pro and Company features unlock air-gapped with no phone-home. Atlas Cloud resolves entitlements and holds billing records, but the runtime does not need a live connection to confirm what a seat is allowed to do.

- **Core** is free, forever.
- **Pro** is a one-time, per-seat license you own, including every update within its major version.
- **Company** is per-seat, annual, with SSO, RBAC, audit logs, and continuous updates while active.

> **Lapses do not brick:** If a Company subscription lapses, the team keeps the last version it was entitled to and simply stops receiving new updates until it renews. See [offline license verification](https://runatlas.sh/resources/features/offline-license-verification).

## Hosted model routing

Bring-your-own-keys and local models are the default. For teams that want one place to set provider policy, enforce rate limits, and account for spend, Atlas Cloud offers an optional hosted **model router** behind an Atlas runtime feature flag.

The router manages routing, provider policy, credit checks, rate limits, and usage events, so an organization can standardize and meter model access without distributing raw provider keys to every seat. It records usage (which model, how much), not the content of your requests.

atlas.json:
```json
{
  "cloud": {
    "model_router": true
  }
}
```

Learn more: [hosted model routing without giving up bring-your-own-keys](https://runatlas.sh/resources/features/hosted-model-routing).

## Telemetry & privacy

Telemetry intake accepts only an **allowlisted event envelope**. Values that look like prompts, model output, provider bodies, or file paths are rejected before they are ever stored, so product analytics never becomes a backdoor for your code or content.

Release and installer manifests expose only public, non-entitlement artifact metadata. Entitlement and usage reads are token-gated. The privacy boundary is a design constraint on what the API accepts, not a policy you have to take on faith.

> **Verify, do not trust:** Because the Atlas binary runs on your machine and Atlas Cloud is contract-driven, you can inspect exactly what leaves your machine. Keep provider keys, MCP servers, and plugins aligned with the privacy policy you promise clients.

## Deployment boundaries

Treat the model route, Atlas operating mode, MCP servers, plugins, provider keys, and local services as one data-flow decision. A local model alone does not make every configured integration local.

| Item | Detail |
| --- | --- |
| Local and offline | Use a local model endpoint plus atlas --offline or ATLAS_OFFLINE=1 to block other outbound Atlas traffic. |
| Private endpoint | Use an approved OpenAI-compatible endpoint with the organization's network, identity, logging, and retention controls. |
| Hosted provider | Treat the selected provider as an external data boundary and review its contract and data policy. |

> **Do not infer the boundary:** Document the exact endpoint and enabled integrations for each regulated deployment. The public security page records current product facts and current assurance gaps.

## Security review checklist

- Record whether Atlas will run offline, against a private endpoint, or against a hosted provider.
- List every MCP server, plugin, credential, local service, and network destination enabled for the workflow.
- Choose allow, ask, and deny rules that match the repository and user role.
- Confirm telemetry and update behavior for the selected operating mode.
- Decide whether any Syntora-operated service will receive, maintain, or transmit PHI before discussing a BAA.
- Review the current assurance status instead of assuming a certification from a product feature.

Use the [Security and Trust page](https://runatlas.sh/security), [integration evidence](https://runatlas.sh/integrations), and [machine-readable security record](https://runatlas.sh/security.json) as the starting packet.

## Slash commands

Open the command palette with `ctrl` `p`, or type a slash command directly into the prompt.

| Command | Description |
| --- | --- |
| `/models` | Switch model, provider, variant, or reasoning mode |
| `/agents` | Choose a primary agent or specialized subagent |
| `/workflow` | Open repeatable workflows for review, refactor, and multi-agent work |
| `/review` | Review uncommitted changes, branches, PRs, or delivery state |
| `/mcps` | Inspect configured Model Context Protocol servers |
| `/sessions` | Resume, fork, or continue previous sessions |
| `/themes` | Switch Atlas themes |
| `/copy-as-slack` | Copy the last assistant message as Slack-ready mrkdwn |
| `/copy-as-gmail` | Copy the last assistant message as email-ready text |
| `/help` | Open the in-app help surface |

## CLI commands

Use CLI commands for updates, scripting, model inspection, server modes, and managing agents or MCP servers. Every command, flag, and default is listed in [the full CLI reference](https://runatlas.sh/cli-reference.md).

| Command | Description |
| --- | --- |
| `atlas` | Start the TUI in the current directory |
| `atlas signup` | Create or sign in to a free Atlas account with a six-digit email code |
| `atlas upgrade` | Update Atlas to the latest or a specific version |
| `atlas models [provider]` | List available models from configured providers |
| `atlas providers` | Manage provider credentials and authentication |
| `atlas mcp` | Add, list, authenticate, debug, and remove MCP servers |
| `atlas agent` | Create and list reusable Atlas agents |
| `atlas run [message]` | Run Atlas non-interactively for scripts and automation |
| `atlas session` | List, resume, fork, export, or delete sessions |
| `atlas serve` | Start a headless Atlas server |
| `atlas web` | Start the server and open the web interface |

## Keybindings

Atlas is keyboard-first. The essentials:

| Keys | Action |
| --- | --- |
| `tab` | Move between prompt, agents, and command surfaces |
| `ctrl p` | Open the command palette |
| `enter` | Submit the current prompt |
| `esc` | Cancel the current interaction or close a dialog |
| `ctrl c` | Quit Atlas |

## Themes

Atlas ships with its own dark terminal theme and can load custom JSON themes from your Atlas config directory. Use `/themes` to switch from the TUI.

custom theme:
```json
{
  "name": "midnight",
  "theme": {
    "primary": "#6aa6f5",
    "background": "#0c0c0c",
    "text": "#e6e9ee"
  }
}
```

## Troubleshooting

#### The `atlas` command is not found

Restart your shell so the updated PATH takes effect, or re-run the install script. On Windows, reopen PowerShell or Windows Terminal.

#### Atlas says it is already installed

Use `atlas upgrade`. If you built Atlas from source, pull the repo, rebuild the package, and make sure your PATH points at the rebuilt binary.

#### A model is missing

Run `atlas models --refresh`. For local models, confirm the model exists with `ollama list` and that Ollama is running.

> **Still stuck?:** Email [contact@runatlas.sh](mailto:contact@runatlas.sh) and we will help.

## Full CLI reference

Every command, subcommand, flag, type, and default: https://runatlas.sh/cli-reference.md

---

Canonical HTML: https://runatlas.sh/docs
Source of truth: src/content/docs.ts (this file is generated from it, never hand-edited).
Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.