Credentials & Auth#

Atlas requires access to sensitive credentials: API keys for LLMs (Anthropic, OpenAI, etc.) and deployment tokens for cloud providers (Vercel, Render, Netlify).

Atlas handles these secrets with strict security principles. Secrets are never stored in plaintext state files, logs, or project-local configurations.

Global Credential Store#

Credentials in Atlas are deliberately global, not project-local. They are tied to the operating system user. Storing them per-project would force you to repeatedly authenticate your Vercel or Anthropic accounts every time you create a new repository.

The credential metadata lives in:

• Windows: %AppData%\atlas\credentials.json
• Linux/macOS: ~/.config/atlas/credentials.json

This JSON file only stores metadata (like verified_at and method). It never stores raw secrets.

How Secrets are Stored#

Atlas uses a two-tier approach to storing the actual secret strings securely:

1. OS Keychain (Default): Atlas leverages the native operating system keychain using go-keyring. On macOS, this uses the Keychain; on Windows, the Credential Manager; and on Linux, Secret Service / DBus.
2. Headless Linux Fallback (0600 file): If you are running Atlas in a CI/CD environment or a headless Linux server without a DBus session, the keychain will fail. Atlas automatically falls back to storing the encrypted string in a file named secrets.fallback.json with strict 0600 permissions (read/write only by the file owner).

Authentication Priority Order#

Whenever Atlas needs to authenticate (either to a cloud provider like Netlify or an LLM like Claude), it evaluates credentials in a strict priority order:

1. Environment Variables (env_var): The highest priority. If you provide an environment variable (e.g., VERCEL_TOKEN, ANTHROPIC_API_KEY, or RENDER_API_KEY), Atlas will use it immediately and bypass all other checks. This is the recommended approach for CI/CD pipelines.
2. Stored OS Keychain Token (stored_token): If no environment variable is present, Atlas checks its global OS keychain store for a previously saved token. You can save tokens explicitly via CLI commands like atlas models set anthropic.
3. CLI Delegation (cli_session): (For Deployment Providers only) If neither of the above is found, Atlas attempts to delegate authentication to the provider's native CLI. For example, if you are already logged in via vercel login or netlify login, Atlas will piggyback on that existing session transparently.

Pre-flight Checks#

Atlas performs a pre-flight auth check (EnsureVercelAuth, EnsureRenderAuth, etc.) before any build work begins. By verifying credentials against the priority order first, Atlas ensures that a missing token fails immediately (in milliseconds) rather than failing three minutes later after a long build process finishes.