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, no API key, no token bill.

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 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

Nothing leaves your machine — you can inspect the script before you run it. When it finishes, confirm the binary is on your PATH:

Terminal window
atomic-agent --help

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?