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 small folder of helpers next to it. Installation is one command; updating is one button.

Developer Preview

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

Supported platforms

v0.5.0 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

Intel Macs are not currently built

There is no darwin-x64 release asset. The macOS x64 build job is disabled in the release workflow, so Intel Macs are not supported today. The install script still derives a darwin-x64 download URL on those machines, which means you get a failed download rather than a clear error message. On an Intel Mac, run from a development checkout instead (see Development checkout below).

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

Then launch the terminal UI to get going:

atomic-agent tui

Tip

Running atomic-agent with no arguments also opens the TUI. The first launch walks you through picking and downloading a local model.

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 self-contained binary that embeds the Node runtime, plus a small vendor/ folder — tens of megabytes in total. 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 (default for desktop use): 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

Managed commands (pull, use, start, stop, update, remove) only work when localModels.mode is managed in your config. In external mode they short-circuit — Atomic Agent expects a server running elsewhere.

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.

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 (model, browser, tasks, memory, MCP servers)
.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

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.

Linux notes

Atomic Agent runs on Linux x64 and arm64. A few desktop capabilities depend on small system packages that are not bundled. Install the ones you want:

Optional Linux desktop packages

• xclip — clipboard read/write (os.clipboard).
• libnotify / notify-send — desktop notifications (os.notify).
• wmctrl — window control (os.window.*). Atomic Agent probes for this at startup and reports it in capabilities.
• 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, which covers all GPU vendors. Managed mode enumerates devices via llama-server --list-devices; prefer 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

The same options exist as browser.* keys in config.json if you prefer not to use environment variables.

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

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.

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
ATOMIC_AGENT_VERSION=v0.5.0 curl -fsSL https://atomicagent.io/install | sh

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).
ATOMIC_AGENT_NO_PATH=1	Skip modifying your PATH.

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:

ATOMIC_AGENT_NO_PATH=1 curl -fsSL https://atomicagent.io/install | 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.

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, browser, memory, and tasks 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.