Skip to content
Atomic Agent logo Atomic Agent docs

Quickstart

Atomic Agent is a local-first operator agent runtime. One inference produces one JSON array of tool calls; the runtime executes those calls, compresses the results, updates durable state, and asks the model for the next move. It runs on your own machine: no cloud account, no API key, and no token bill with local models.

This page takes you from nothing to a working agent in three steps: install, start a model, run. Everything below is copy-paste.

1. Install

On macOS (Apple Silicon) or Linux, run the one-line installer:

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

On Windows, run it in PowerShell:

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

You can inspect the script before you run it. When it finishes, confirm the binary is on your PATH:

Terminal window
atomic-agent --help

The installer also adds atag, a shorter alias for the same binary.

Prefer an app over the terminal? The Atomic Agent desktop app for macOS, Windows, and Linux ships the agent inside and walks you through picking a model. See Desktop app.

2. Start a local model

Atomic Agent talks to a local llama-server. The simplest path is managed mode — the CLI downloads the llama.cpp backend and a model for you, then runs the daemon. Pull the default model, select it, and start the server:

Terminal window
# Download the default model (a small, fast quantized model)
atomic-agent models pull qwen-3.5-4b


# Make it the active model
atomic-agent models use qwen-3.5-4b


# Start the managed llama-server daemon
atomic-agent models start


# Confirm it's healthy
atomic-agent models status

models status polls the server’s /health endpoint and should report ok once the model is loaded. The first pull downloads a few GB, so it takes a minute — after that the model is cached locally.

3. Run it

Start the agent:

Terminal window
atomic-agent

Or open the terminal UI scoped to a working directory:

Terminal window
atomic-agent tui --cwd /path/to/work

You’ll land in the TUI with Run · Observe · Manage tabs and a status bar showing your model and health. Type a request at the prompt and press Enter — for example:

Summarize every .md file in this folder into a single outline.

The agent reads the files, drafts the outline, and replies. Anything risky — writing a file, running a shell command — pauses for your approval first, so you stay in control of every side effect.

What next?