Atlas UI 3

Atlas UI 3 is an open-source platform for deploying AI assistants and agentic workflows in high-trust engineering environments. Developed by Sandia National Laboratories -- a U.S. Department of Energy national laboratory -- Atlas connects securely to leading LLMs, external tools, enterprise data sources, and MCP (Model Context Protocol) servers so teams can build AI applications that do more than answer questions.

It is designed for regulated and security-conscious organizations that need more than a chatbot: configurable model access, group-based authorization, tool approval controls, compliance levels, RAG, auditable workflows, and containerized deployment options to help teams understand, govern, and operate the full AI application stack.

About the Project

Atlas UI 3 is a full-stack platform for AI assistants and agentic workflows with support for multiple models, including OpenAI, Anthropic, and Google. Its core integration with the Model Context Protocol (MCP) allows assistants to connect to external tools and data sources, enabling complex, real-time workflows in environments where control and traceability matter.

Features

• Multi-LLM Support: Connect to various LLM providers with configurable model access.
• MCP Integration: Connect assistants to MCP servers, custom tools, and external data sources.
• RAG Support: Enhance responses with Retrieval-Augmented Generation.
• Governance and Access Control: Features group-based authorization, compliance levels, and a tool approval system.
• Containerized Deployment: Run Atlas in Docker or Podman-based environments.
• Modern Stack: Built with React 19, FastAPI, and WebSockets.
• Python Package: Install and use as a library or CLI tool.

Installation

Install from PyPI (Recommended for Users)

# Install the package
pip install atlas-chat

# Or with uv (faster)
uv pip install atlas-chat

CLI Usage

After installation, three CLI tools are available:

# Set up configuration (run this first!)
atlas-init                          # Creates .env and config/ in current directory
atlas-init --minimal                # Creates just a minimal .env file
atlas-init --env-file ~/.atlasrc    # Write .env to a custom location (shared installs)

# Chat with an LLM
atlas-chat "Hello, how are you?"
atlas-chat "What is 2654687621*sqrt(2)?" --tools calculator_evaluate
atlas-chat --list-tools
atlas-chat --list-models

# Start the web server
atlas-server --port 8000
atlas-server --env-file /path/to/.env --config-folder /path/to/config
# Or set ATLAS_ENV_FILE once and all Atlas commands pick it up:
export ATLAS_ENV_FILE=~/.atlasrc

Python API Usage

import asyncio
from atlas import AtlasClient

async def main():
    client = AtlasClient()

    # Simple chat
    result = await client.chat("Hello, how are you?")
    print(result.message)

    # Use the calculator MCP tool (the model calls it natively via tool_choice="auto")
    result = await client.chat(
        "What is 1234 * 5678?",
        selected_tools=["calculator_evaluate"],
    )
    print(result.message)

    await client.cleanup()

asyncio.run(main())

Synchronous usage:

from atlas import AtlasClient

client = AtlasClient()
result = client.chat_sync("Hello!")
print(result.message)

Quick Start (Development)

Prerequisites

# Install uv package manager (one-time)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install in editable mode (with dev dependencies)
uv venv && source .venv/bin/activate
uv pip install -e ".[dev,mcp-demos]"   # mcp-demos: deps the bundled demo MCP servers need

This installs the atlas package in editable mode, meaning:

• All dependencies are installed from pyproject.toml (the single source of truth)
• The atlas package is importable everywhere without needing PYTHONPATH
• Edit any Python file in atlas/ and changes take effect immediately
• CLI commands (atlas-chat, atlas-server, atlas-init) are available
• Dev tools (pytest, ruff, podman-compose) are included

Alternative: PYTHONPATH (if you can't use editable install)

# Set PYTHONPATH manually when running
PYTHONPATH=/path/to/atlas-ui-3 python atlas/main.py

Local Experimentation and MCP Testing

If you cloned the repo and want to run tests, experiment locally, or test MCP servers, sync the dev dependencies:

uv sync --dev

This installs pytest, ruff, MCP demo server dependencies (matplotlib, pandas, etc.), and other development tools into your virtual environment.

Extract Pre-Built Frontend from PyPI Package

On a machine without Node.js, you can extract the pre-built frontend assets from the published PyPI wheel instead of running npm run build.

# Create a throwaway venv and install the package into it
uv venv ./tmp/atlas-extract --python 3.11
uv pip install atlas-chat --target ./tmp/atlas-extract/site

# Copy the static files into your cloned repo
cp -r ./tmp/atlas-extract/site/atlas/static/ atlas/static/

# Clean up
rm -rf ./tmp/atlas-extract

The server checks atlas/static/ first, then falls back to frontend/dist/. Once the files are in place, bash agent_start.sh will serve the frontend without needing Node.js.

Running the Application

Linux/macOS:

bash agent_start.sh

Windows:

.\ps_agent_start.ps1

Note for Windows users: If you encounter frontend build errors related to Rollup dependencies, delete frontend/package-lock.json and frontend/node_modules, then run the script again.

Both scripts automatically detect and work with Docker or Podman. The agent_start.sh script builds the frontend, starts necessary services, and launches the backend server.

Documentation

We have created a set of comprehensive guides to help you get the most out of Atlas UI 3.

• Getting Started: The perfect starting point for all users. This guide covers how to get the application running with Docker or on your local machine.

• Administrator's Guide: For those who will deploy and manage the application. This guide details configuration, security settings, access control, and other operational topics.

• Developer's Guide: For developers who want to contribute to the project. It provides an overview of the architecture and instructions for creating new MCP servers.

Releases

Atlas UI 3 ships on a weekly, fully automated cadence. Every Monday the release-weekly workflow checks CHANGELOG.md and, when there are unreleased entries, bumps atlas/version.py and pyproject.toml, refreshes uv.lock, finalizes the CHANGELOG.md section, opens a version-bump PR, waits for CI to go green, merges it, tags the merge commit vX.Y.Z, and publishes a GitHub Release. A week with no unreleased changes is skipped. The tag builds the container images and the Release publishes the Python package — no human step is required. release-cut remains available as a manual-only escape hatch for a genuine stabilization freeze.

The full runbook — versioning (SemVer), the automation, failure recovery, the manual/stabilization/hotfix flows, rollback — lives in docs/developer/release-process.md. Published versions land on PyPI and as container images on Quay.io.

Docker / Podman

Quick Start

The canonical Dockerfile is a multi-stage build that runs as UID/GID 10001:10001 and drops sudo, Node.js/npm, pip, and the test//docs//scripts/ trees. It requires three secrets at runtime:

# 1. Generate deployment secrets (reuse them across restarts and workers)
export MCP_TOKEN_ENCRYPTION_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
export CAPABILITY_TOKEN_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
export PROXY_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")

# 2. Set up local config (copies defaults from atlas/config/)
atlas-init
# Edit .env to add your API keys

# 3. Build the image
podman build -t atlas-ui-3 .

# 4. Run with your local config mounted
podman run -p 127.0.0.1:8000:8000 \
  -v $(pwd)/config:/app/config:Z \
  -e MCP_TOKEN_ENCRYPTION_KEY="$MCP_TOKEN_ENCRYPTION_KEY" \
  -e CAPABILITY_TOKEN_SECRET="$CAPABILITY_TOKEN_SECRET" \
  -e PROXY_SECRET="$PROXY_SECRET" \
  --env-file .env \
  atlas-ui-3

Proxy-secret enforcement is on by default, so reach the UI through an authenticating reverse proxy that injects X-Proxy-Secret and a verified identity header. The HEALTHCHECK only probes /api/heartbeat; it does not test authentication. The container seeds /app/config from package defaults at build time; mount your local config/ folder to override llmconfig.yml, mcp.json, etc. without rebuilding.

Runtime-only Image (compatibility entry point)

Dockerfile.runtimeonly is a thin shim that reuses the canonical image rather than maintaining a second recipe. It defaults to the published tag, so pass --build-arg ATLAS_RUNTIME_IMAGE only to point at a locally built image:

podman build -f Dockerfile.runtimeonly -t atlas-ui-3-runtime .
podman run -p 127.0.0.1:8000:8000 \
  -v $(pwd)/config:/app/config:Z \
  -e MCP_TOKEN_ENCRYPTION_KEY="$MCP_TOKEN_ENCRYPTION_KEY" \
  -e CAPABILITY_TOKEN_SECRET="$CAPABILITY_TOKEN_SECRET" \
  -e PROXY_SECRET="$PROXY_SECRET" \
  --env-file .env \
  atlas-ui-3-runtime

Container Images

Pre-built container images are available at quay.io/agarlan-snl/atlas-ui-3:latest (pushes automatically from main branch).

For AI Agent Contributors

If you are an AI agent working on this repository, please refer to AGENTS.md for all project conventions, architecture, and development guidance.

Citing Atlas-UI-3

If you use Atlas-UI-3 in a publication, please cite:

Melander, Darryl, Garland, Anthony, Lancaster, Caitlin, & Bernauer, Michael. Atlas-UI-3. Sandia National Laboratories (SNL-NM), Albuquerque, NM, 2025. https://doi.org/10.11578/dc.20260211.11

BibTeX:

@misc{atlas_ui_3,
  author = {Melander, Darryl and Garland, Anthony and Lancaster, Caitlin and Bernauer, Michael},
  title = {Atlas-UI-3},
  year = {2025},
  month = {10},
  doi = {10.11578/dc.20260211.11},
  url = {https://www.osti.gov/biblio/code-175384}
}

License

Copyright 2025 National Technology & Engineering Solutions of Sandia, LLC (NTESS). Under the terms of Contract DE-NA0003525 with NTESS, the U.S. Government retains certain rights in this software

MIT License