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. Commands, config keys, and behavior still move between releases. For a stable integration, pin a specific release rather than tracking latest. macOS, Linux x64/arm64, and Windows are all supported.

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 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 binary is ~8–9 MB, but models are much larger. 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.

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. Set the URL via environment variable:

export ATOMIC_AGENT_LLAMA_URL="http://127.0.0.1:8080"
atomic-agent run

Or set it in config.json:

{
  "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.

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.

A couple of honest caveats:

• No auto-restart. The update takes effect on your next manual relaunch — Atomic Agent will not restart the process for you.

You can control the startup check with environment variables:

# Disable the on-startup update check
export ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP=0

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

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.x.y curl -fsSL https://atomicagent.io/install | sh

The install script also honors ATOMIC_AGENT_INSTALL_DIR to choose where the binary lands.

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

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 ATOMIC_AGENT_LLAMA_URL and skip managed downloads.

Hit a snag?

Model server, GPU, ports, or browser issues — see Troubleshooting.