Install & Update

Atomic Agent is a local-first AI agent that runs on your own machine. There’s no cloud account to create and no per-token bill — it talks to a language model running locally and keeps your data on disk. This page gets it installed and ready to run.

The whole app ships as a single binary with a few support folders next to it. Installation is one command, and so is updating: atomic-agent update, or confirm the update prompt in the TUI.

Developer Preview

Atomic Agent is a Developer Preview (current release v0.6.5). Commands, config keys, and behavior still move between releases. For a stable integration, pin a specific release rather than tracking latest.

Supported platforms

v0.6.5 publishes prebuilt binaries for exactly four targets:

Platform	Target	Status
macOS (Apple Silicon)	darwin-arm64	Supported
Linux x64	linux-x64	Supported
Linux arm64	linux-arm64	Supported
Windows x64	win32-x64	Supported

Windows on ARM runs the x64 build under emulation; the PowerShell installer installs it and prints a note.

Intel Macs are not currently built

There is no darwin-x64 release asset (the macOS x64 build job is disabled), so Intel Macs are not supported today. On an Intel Mac the installer stops with “no published build for darwin-x64” and prints the build-from-source steps. See Installing from source.

Quick install

The fastest path is the install script. It downloads the right binary for your platform, verifies it, and puts it on your PATH.

On macOS (Apple Silicon) or Linux, run it in your shell:

curl -fsSL https://atomicagent.io/install | sh

On Windows, run it in PowerShell:

irm https://atomicagent.io/install.ps1 | iex

Once it finishes, confirm the binary is found:

atomic-agent --help

The installer also adds atag, a shorter alias for the same binary, so atag tui and atomic-agent tui do the same thing.

Then launch the terminal UI to get going:

atomic-agent tui

First-run setup

Running atomic-agent with no arguments also opens the TUI. On a fresh install it starts a guided setup: pick a local model (it downloads the model and the llama.cpp backend for you), a cloud provider, or your own server URL. The last step offers to import data such as skills and sessions from another agent it finds on your machine (Hermes, OpenClaw, Claude Code, Codex, Pi, Oh-My-Pi), with a preview before anything is written. You can skip it.

What you need

Atomic Agent bundles most of what it needs into the binary, but a few things live outside it and must be present on your system.

A local model server

Inference runs through llama-server (from llama.cpp). Atomic Agent can download and manage this for you (managed mode), or you can point it at a server you run yourself (external mode).

A browser (optional)

Browser tools drive Chrome, Edge, or Chromium. Browser binaries are not bundled — install one yourself if you want web automation.

Disk + RAM/VRAM

The download is a ~50 MB archive. It unpacks to a ~140 MB self-contained binary (it embeds the Node runtime) plus a few support folders next to it (vendor/, node_modules/, grammars/, starter-skills/). Models dominate the footprint: the default model (qwen-3.5-4b) needs a few GB. GPU acceleration is used when available.

Linux desktop tools

Some Linux tools (clipboard, notifications, window control) rely on small system packages. See Linux notes below.

Node.js 25.7+ (source installs only)

The prebuilt binary needs no Node at all. Building or running from source requires Node.js 25.7.0 or newer — see Installing from source.

What’s already inside the binary, so you don’t install it separately:

• ripgrep — fast file search (shipped as vendor/rg next to the binary).
• Document extractors — PDF, DOCX, XLSX, PPTX, RTF, ODT text extraction.
• SQLite — sessions, memory, and tasks are stored locally.

How the pieces fit

Atomic Agent is the binary you install. It connects out to a model server for inference and, optionally, to a browser for web tasks. Everything else — your sessions, memory, and config — lives in a local state directory.

flowchart LR
    subgraph machine["Your machine"]
        CLI["atomic-agent<br/>(single binary)"]
        Llama["llama-server<br/>(llama.cpp)"]
        Browser["Chrome / Edge<br/>(optional)"]
        State["~/.atomic-agent<br/>config.json, .env,<br/>sessions, memory"]
    end

    CLI -->|inference| Llama
    CLI -->|web tools| Browser
    CLI -->|read/write| State

    Install["install.sh"] -->|downloads| CLI
    Llama -->|managed mode<br/>downloads| Models["GGUF models<br/>(HuggingFace)"]

• Managed mode (recommended; the TUI’s first-run setup and models use switch you to it): Atomic Agent downloads llama-server and your chosen model, starts the daemon, and watches its health.
• External mode: you run llama-server yourself; Atomic Agent just talks to it.

Set up the model server

You have two ways to provide inference.

Managed (recommended)

Let Atomic Agent handle the model server for you. Inside the TUI’s first-run setup, or from the CLI:

# See the catalog of available chat models
atomic-agent models list

# Download and select a model (qwen-3.5-4b is the default)
atomic-agent models pull qwen-3.5-4b
atomic-agent models use qwen-3.5-4b

# Start the managed daemon
atomic-agent models start

# Check it's healthy
atomic-agent models status

Managed mode downloads the llama.cpp backend and the GGUF model, spawns the daemon, and polls its /health endpoint until it reports ok. To upgrade the backend or swap models later, use atomic-agent models update, models pull, and models stop.

Note

models use <id> switches localModels.mode to managed. In external mode, models start and models update refuse, and models status only prints the configured URL instead of probing it.

External

If you already run llama-server (or run it on another host), point Atomic Agent at it. The URL comes from config.json — there is no environment variable for it:

{
  "localModels": {
    "url": "http://127.0.0.1:8080",
    "mode": "external"
  }
}

If your server requires a bearer token, provide it with ATOMIC_AGENT_LLAMA_API_KEY.

GPU backends

Managed mode downloads the llama.cpp build that fits your platform. An NVIDIA GPU is not required.

Platform	Backend
macOS (Apple Silicon)	Metal
Linux x64	Vulkan (NVIDIA, AMD, Intel)
Linux arm64	CUDA 13.3 build that falls back to CPU without an NVIDIA driver; needs glibc 2.38+
Windows x64	CUDA 12.4 or 13.3 when nvidia-smi reports a capable driver, otherwise Vulkan; falls back to the CPU build automatically if the GPU build can’t serve

Run atomic-agent models devices to see what was detected and models use-device to pick one.

First run

With a model ready, start a session:

# Interactive terminal UI
atomic-agent tui

# Or a plain stdin/stdout chat loop
atomic-agent run --cwd .

Useful flags on run:

• --cwd DIR — set the working directory the agent operates in.
• --max-steps N — cap how many steps a single turn may take.
• --no-approval — auto-approve dangerous tools (shell, file writes, HTTP). Convenient for trusted/dev use; risky otherwise.

Caution

--no-approval bypasses the approval gate entirely. Dangerous tools run without asking, and you lose visibility into what the agent did. Only use it in environments you trust.

Where Atomic Agent stores things

Everything lives in a single state directory, defaulting to ~/.atomic-agent. Override it with ATOMIC_AGENT_STATE_DIR.

Path	What it holds
config.json	User-facing settings (local models, agent limits and approvals, memory, MCP servers, channels, analytics)
.env	Secrets — API keys, tokens (mode 0600)
sessions.sqlite	Conversation transcripts and session state
memory.sqlite	Profile facts, notes, lessons, procedures
tasks.sqlite	Durable task queue
skills/	Globally installed skills
models/	Downloaded GGUF models and the managed llama.cpp backend
traces/	Per-session NDJSON traces

Secrets are not redacted

.env and any API keys in config.json are stored in plaintext on disk. Treat your state directory as sensitive. Prefer putting secrets in .env (which is chmod’d 0600) over config.json.

Telemetry

Your conversations, files, and memory stay in this directory by default. Anonymous usage analytics (PostHog) and crash reports (Sentry) are on by default. One switch in config.json turns both off:

{ "analytics": { "enabled": false } }

Linux notes

Atomic Agent runs on Linux x64 and arm64. A few desktop capabilities depend on small system packages that are not bundled. Atomic Agent probes for clipboard, notification, and window tools at startup and reports what it found in its capabilities. Install the ones you want:

Optional Linux desktop packages

• xclip, xsel, or wl-clipboard (Wayland): clipboard read/write (os.clipboard).
• libnotify / notify-send: desktop notifications (os.notify).
• wmctrl: window control (os.window.*).
• gio: trash/move-to-trash support.

ripgrep is already bundled, so you do not need to install it separately. (To point at a different ripgrep, set ATOMIC_AGENT_RG_PATH.)

Two more things to know on Linux:

• GPU acceleration uses Vulkan on Linux x64 (NVIDIA, AMD, and Intel). On Linux arm64 there is one backend build (CUDA 13.3 with CPU fallback, ~554 MB) and it needs glibc 2.38+ (Ubuntu 24.04, Debian 13, DGX OS 7); on older or musl systems use external mode. Managed mode enumerates devices via llama-server --list-devices and prefers a discrete GPU when present.
• Browser sandboxing can fail inside containers or unusual kernels. If Chrome won’t launch, set ATOMIC_AGENT_BROWSER_NO_SANDBOX=1 (containers/CI only — it disables the browser sandbox).

Browser setup (optional)

Browser binaries aren’t shipped with Atomic Agent — install Chrome, Edge, or Chromium yourself. Then tune behavior with environment variables:

# Which browser channel to drive
export ATOMIC_AGENT_BROWSER_CHANNEL=chrome   # chrome | msedge | chromium

# Explicit binary path (overrides auto-detect)
export ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium

# Run headless
export ATOMIC_AGENT_BROWSER_HEADLESS=1

# Attach to an already-running browser via CDP instead of launching one
export ATOMIC_AGENT_BROWSER_CDP_URL=http://127.0.0.1:9222

These are environment variables only; config.json has no browser section.

Installing from source

Building from a checkout is the fallback when there’s no prebuilt binary for your machine — notably Intel Macs.

Node.js 25.7.0 or newer is required

package.json declares "engines": { "node": ">=25.7.0" }. This is a very new runtime, and most systems ship something older, so npm install will fail if you’re behind. Check first:

node --version   # must be v25.7.0 or higher

If it’s lower, upgrade Node before going any further — the failure otherwise surfaces as an unrelated-looking install error.

git clone https://github.com/AtomicBot-ai/atomic-agent
cd atomic-agent
npm install
npm run build

Then run it with node dist/cli/index.js (or npm link to get atomic-agent and atag on your PATH).

The prebuilt binary has no such requirement: it embeds its own Node runtime, so you never install Node to use a released build.

Updating

How you update depends on how you installed.

In-app (installed binary)

If you installed via the script, Atomic Agent can update itself. When the TUI starts, it checks GitHub for a newer release (when eligible) and surfaces a prompt. Confirm it, and Atomic Agent re-runs the install script in place.

The check is a single anonymous GET to the GitHub Releases API (/repos/<repo>/releases/latest) and compares the latest tag with your running version. It is fire-and-forget: if you are offline, rate-limited, or the API errors, the failure is swallowed and your launch proceeds as normal. The result is cached in-process for ten minutes, so rapid relaunches do not re-query. If GITHUB_TOKEN or GH_TOKEN is set in your environment, it is sent as a bearer token to lift the anonymous rate limit.

Two honest caveats:

• No silent auto-restart. Atomic Agent will not restart the running process for you. Once the update is written, the TUI shows a restart prompt so you know the new version is waiting — it takes effect when you relaunch.
• Installed binary only. Self-update is refused when the running process is node or tsx, so it can never overwrite your Node runtime. See the Development checkout tab.

From a shell, atomic-agent update does the same thing. --check only reports current vs latest, and --version v0.6.5 installs a specific tag. The running process is not restarted; the next launch picks up the new binary.

atomic-agent update            # install the latest release
atomic-agent update --check    # report only, install nothing

The update settings are environment-only — there is no update block to add to config.json:

Setting	Variable	Default
Startup version check	ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP	true
Repository queried and installed from	ATOMIC_AGENT_REPO	AtomicBot-ai/atomic-agent

# Disable the on-startup update check (skips the network call and the prompt)
export ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP=0

# Target a fork or a specific repo
export ATOMIC_AGENT_REPO=AtomicBot-ai/atomic-agent

ATOMIC_AGENT_REPO sets both halves of the flow: the release the check looks at, and the install.sh (or install.ps1) the in-app update downloads and runs.

Re-run the script

You can always update by re-running the install command. Pin a version for reproducible installs:

# Latest
curl -fsSL https://atomicagent.io/install | sh

# Pin a specific release (the variable goes on `sh`, not on `curl`)
curl -fsSL https://atomicagent.io/install | ATOMIC_AGENT_VERSION=v0.6.5 sh

On Windows:

$env:ATOMIC_AGENT_VERSION = "v0.6.5"; irm https://atomicagent.io/install.ps1 | iex

The install script (and its PowerShell counterpart) honors these environment variables:

Variable	What it does
ATOMIC_AGENT_VERSION	Install a specific release tag instead of the latest.
ATOMIC_AGENT_INSTALL_DIR	Choose where the binary lands (default $HOME/.local/bin; on Windows %LOCALAPPDATA%\atomic-agent).
ATOMIC_AGENT_NO_PATH=1	Skip modifying your PATH.
ATOMIC_AGENT_VERIFY_TIMEOUT	Seconds allowed for the macOS signature check (default 20; 0 skips it). install.sh only.

Set ATOMIC_AGENT_NO_PATH=1 when you manage your own PATH — in a Dockerfile, a dotfiles repo, or a CI image. The installer then leaves your shell rc file (or, on Windows, your user PATH) untouched and just prints the line you’d need to add yourself:

curl -fsSL https://atomicagent.io/install | ATOMIC_AGENT_NO_PATH=1 sh
# add to PATH: export PATH="$HOME/.local/bin:$PATH"

Note that the binary is still installed normally — only the PATH edit is skipped, so atomic-agent will not be found until you add its directory yourself.

Development checkout

If you’re running from source (via node/tsx), self-update is intentionally disabled so it never overwrites your Node runtime. Update through your package manager or git instead:

git pull
npm install
npm run build

Same requirement as a fresh source install: Node.js 25.7.0 or newer. See Installing from source.

Note

The model backend updates separately from the app. To refresh the managed llama.cpp backend, run atomic-agent models update.

Uninstalling

atomic-agent uninstall --dry-run   # show what would be removed
atomic-agent uninstall

It lists everything it will delete with sizes: the state directory (config, memory, sessions, tasks, traces, and downloaded models), the binary and its atag alias, the support folders next to it, and the PATH line the installer added to your shell rc file. Then it asks you to type uninstall to confirm. There is no backup.

• --keep-data keeps the state directory and removes only the program.
• --keep-binary keeps the program and removes only the data.
• --keep-path leaves the installer’s PATH line alone.
• Non-interactive runs need --yes.

The TUI has the same action as /uninstall.

Next steps

Run your first task Open the TUI with atomic-agent tui and ask the agent to do something real — read a file, search the web, or run a command.

Configure it Tune models, agent limits, memory, and MCP servers in config.json. See the Configuration reference.

Serve an API atomic-agent serve exposes an OpenAI-compatible endpoint at POST /v1/chat/completions.

Bring your own model server Prefer external mode? Set localModels.url in config.json and skip managed downloads.

Hit a snag? Model server, GPU, ports, or browser issues: see Troubleshooting.