CLI Reference

atomic-agent is the single command-line tool for running the agent, serving it over HTTP, scheduling background work, managing local models and skills, and inspecting what happened after the fact. This page lists every command and every flag.

If you just want to start chatting, run atomic-agent with no arguments — it opens the terminal UI.

Runtime requirement

The prebuilt binary embeds its own Node runtime, so you do not need Node to use a release. Building or running from source requires Node.js 25.7.0 or newer (see Installing from source).

Developer Preview

Atomic Agent is a Developer Preview. Command names, flags, and config keys still move between releases. Pin a release if you depend on the exact surface below.

At a glance

atomic-agent [command] [flags]

There are 12 public top-level commands, plus a hidden debug repl. Running atomic-agent with no command opens the TUI.

Command	What it does
run	Interactive chat loop on stdin/stdout
tui	Full terminal UI (default when no command is given)
serve	Start the OpenAI-compatible HTTP server (and any enabled Telegram/Discord channels)
task	Manage the durable task queue (schedule, list, run)
trace	Inspect, export, and replay recorded sessions
skill	Install, list, and toggle skills
models	Manage local llama.cpp models and GPU devices, and search cloud models
config	Read, set, or reset keys in config.json
memory	Export the memory store to an Obsidian vault
import	Migrate from Claude Code, Codex, Hermes, OpenClaw, Pi or Oh-My-Pi
update	Self-update the installed binary from GitHub Releases
uninstall	Remove the binary and/or all of its data from this machine

A few entry points sit outside the table:

• atag is a short alias for atomic-agent, installed next to the binary by the install script. atag run and atomic-agent run are the same thing.
• atomic-agent --version (also -v or version) prints the installed version, for example atomic-agent 0.6.5.
• atomic-agent help <command> is the same as atomic-agent <command> --help. atomic-agent --help lists every command.
• atomic-agent repl is a scaffold debug REPL. It is not listed in --help and is not a substitute for run or tui.

Exit codes: 0 success, 1 failure, 2 usage error. The 2 split is implemented by run, skill, memory, update, uninstall, and the dispatcher itself (unknown command). config, serve, trace, task, models and import return 1 for usage errors as well, so a 1 from them does not always mean the work failed. trace replay uses 2 to mean “drift detected”. tui can pass through a relaunched child’s status (for example 130 after Ctrl-C), and repl always returns 0.

flowchart TD
    A["atomic-agent [command]"] --> B{command}
    B -->|none| TUI["tui"]
    B -->|run| RUN["interactive chat loop"]
    B -->|serve| SRV["HTTP server + approval bus"]
    B -->|task| TSK["TaskStore / TaskRunner"]
    B -->|trace| TRC["trace files (NDJSON)"]
    B -->|skill| SK["skill install / toggle"]
    B -->|models| MD["managed llama.cpp daemon"]
    B -->|config| CF["config.json"]
    B -->|import| IM["migration from other agents"]
    RUN --> RT["runtime.runTurn"]
    SRV --> RT
    TSK --> RT

Commands

Run — interactive chat

Starts the agent in a plain stdin/stdout chat loop. Type a message, press Enter, and the agent runs a turn and prints its reply. Diagnostics go to stderr; the assistant’s reply goes to stdout.

atomic-agent run [--cwd DIR] [--max-steps N] [--no-approval]

Flag	Default	Description
--cwd DIR	current directory	Working directory the agent resolves relative paths against and scopes the session to.
--max-steps N	agent.task.maxSteps (1000)	Hard ceiling on steps for one task. Without it, the agent works in legs of agent.maxSteps (25) steps and continues automatically up to agent.task.maxSteps (1000) or agent.task.maxDurationMs (2 hours). --max-steps can also raise the ceiling above 1000.
--no-approval	off	Force approval level 5 (approve everything) for this process. See the caution below.

At the default approval level (1), dangerous tools pause and prompt you over stdin. Approval is serial: a long-running approval blocks later ones in the same turn.

The approval prompt

The stdin prompt takes four answers, not two:

Answer	Effect
y	Approve this one call.
s	Approve, and allow this whole category (file writes, HTTP, shell…) for the rest of the session.
a	Approve, and allow this shell command shape for the rest of the session.
N	Deny. Anything that is not y, yes, s, or a is a refusal.

s and a only appear when the request is grantable. Writes to the agent’s own trust config (config.json, .env) are never grantable — those requests only ever offer y/N, because a silent write there could raise the ladder for the next boot.

Caution

--no-approval sets approval level 5 — shell commands, filesystem writes, and HTTP requests run with no confirmation. The onApprovalRequest callback never fires, so you also lose visibility into what the agent did. The flag is one-directional: it can only lower strictness for one run, never raise it. Use it for trusted automation only.

Note

Assistant replies are collapsed to a single line (newlines become spaces) so line-synced eval harnesses stay aligned. The full multi-line text is preserved in the trace NDJSON — use atomic-agent trace show to read it.

TUI — terminal UI

Launches the full React/Ink terminal interface: chat plus tabs for tasks, skills, memory, MCP, providers, local models, and Telegram. This is what runs when you type atomic-agent with no command.

atomic-agent tui [--cwd DIR] [--max-steps N] [--no-approval] [--skip-llama-setup]
                 [--onboarding] [--mouse | --no-mouse]

Flag	Default	Description
--cwd / --working-dir DIR	current directory	Working directory for the session.
--max-steps N	agent.task.maxSteps (1000)	Hard step ceiling for one task, same meaning as for run.
--no-approval	off	Force approval level 5 (approve everything). In the TUI, approvals otherwise appear as a modal.
--skip-llama-setup	off	Skip the first-run model setup wizard. Also settable via ATOMIC_AGENT_TUI_SKIP_LLAMA_SETUP=1.
--onboarding	off	Run first-time setup again. Providers, keys, and sessions are kept.
--mouse	tui.mouse (true)	Force terminal mouse support on for this run.
--no-mouse	off	Turn mouse support off for this run, which restores the terminal’s own drag-to-select.

The TUI needs an interactive terminal. In scripts, use atomic-agent run.

Inside the TUI, slash commands drive everything: /help, /new, /clear, /abort, /quit, /theme, plus panel switches like /tasks, /skills, /memory, /mcp, /llm, /models, /telegram, and /import. Sessions are created lazily on your first message, so opening the TUI just to glance at settings does not litter the session store.

Serve — HTTP server

Starts a Node HTTP server exposing an OpenAI-compatible chat API plus Atomic Agent management endpoints. Listens until SIGINT (Ctrl-C) or SIGTERM.

serve boots the same runtime as the TUI, so enabled Telegram and Discord channels (and swarm bots that have a token) run in this process too. A channel runs in one process at a time; a second process reports it as already running.

atomic-agent serve [--host H] [--port P] [--cwd DIR] [--api-key K] [--no-approval]

Flag	Default	Description
--host H	127.0.0.1	Address to bind.
--port P	8787	Port to listen on.
--cwd DIR	current directory	Working directory for sessions.
--api-key K	ATOMIC_AGENT_API_KEY env var	Bearer token required on authenticated routes. If both are omitted, auth is disabled.
--no-approval	off	Force approval level 5 (approve everything) for all requests.

Authenticated routes expect an Authorization: Bearer <token> header. Two routes are intentionally public so OpenAI SDKs can probe them before sending a key: GET /health and GET /v1/models.

HTTP endpoints exposed by serve

Method & path	Purpose
POST /v1/chat/completions	OpenAI-compatible chat, streaming or sync.
POST /v1/chat/completions/{id}/cancel	Abort a streaming completion by id.
GET /v1/models	Model catalog (public, single atomic-agent entry).
GET /health	Liveness probe (public).
GET /api/capabilities	Runtime wiring summary.
GET|PATCH /api/config	Read the user config, or rewrite it. PATCH has a known issue that resets most blocks, see the HTTP server page.
GET /api/skills, GET /api/skills/{name}	List / inspect skills.
POST /api/skills/install, /api/skills/uninstall	Manage skills.
GET /api/sessions, GET|DELETE /api/sessions/{id}	List / fetch / delete sessions.
POST|GET|DELETE /api/sessions/{id}/steer	Steer a running turn, list steers it never consumed, acknowledge them.
POST /api/approval/resolve	Resolve a pending approval.
GET /api/events	SSE stream of approval requests (replays pending on connect).
POST|GET /api/tasks, GET|DELETE /api/tasks/{id}	Task CRUD.
POST /api/tasks/{id}/run, POST /api/tasks/drain	Trigger task execution.
POST /api/webhooks/{name}	Webhook ingress, materialized as a task.

Custom headers: X-Atomic-Session-Id (request/response) pins the session; X-Atomic-Completion-Id is returned on completions (pass it to the cancel route); X-Atomic-Extensions opts into named SSE events (e.g. tool_progress) instead of the strict OpenAI subset; X-Webhook-Secret authenticates webhook posts.

Task — durable task queue

Schedule deferred or recurring agent turns. Tasks persist to SQLite and survive restarts. Reads (list, show) use the task store directly; create for recurring schedules and run boot the full runtime.

atomic-agent task list   [--session ID] [--status CSV] [--limit N]
atomic-agent task show   <id>
atomic-agent task create [--session ID] --message TEXT
                         [--at MS | --cron EXPR | --every SEC] [--tz IANA]
                         [--notify telegram]
                         [--max-attempts N] [--max-steps N]
atomic-agent task cancel <id>
atomic-agent task run    <id> | --all-pending [--session ID]
atomic-agent task tick   [--limit N]

Subcommand	Notes
list	Filter by --session, comma-separated --status, and --limit.
show <id>	Print one task record.
create	--message is required. Pick at most one schedule: --at (epoch ms one-shot), --cron (cron expression), or --every (interval in seconds). --tz sets the IANA timezone and is only valid together with --cron — passing it with --at, --every, or no schedule at all is an error. --notify telegram pings you over the Telegram channel when the task finishes; telegram is the only accepted value.
cancel <id>	Idempotent cancel.
run <id> / --all-pending	Execute now, applying retry backoff between attempts.
tick [--limit N]	One-shot drain of all due tasks, then exit. Exits 1 if any task failed or was blocked. Good for cron-style ops.

run and tick run at approval level 5

task run and task tick execute with approval level 5: every gated action (shell, file writes, HTTP) runs without asking, whatever agent.approvalLevel says. The same applies when task create boots the runtime for a recurring schedule. Only queue tasks you would be comfortable running unattended.

--at takes epoch milliseconds only

--at is parsed with parseInt, so an ISO date string is not accepted — and it fails silently rather than loudly. --at 2026-08-18T09:00:00Z parses to the number 2026, which is a timestamp 56 years in the past, and the task fires immediately. Always pass milliseconds since the Unix epoch:

# Linux (GNU date)
atomic-agent task create --message "post the digest" \
  --at "$(date -d '2026-08-18T09:00:00Z' +%s000)"

# macOS (BSD date)
atomic-agent task create --message "post the digest" \
  --at "$(date -j -u -f '%Y-%m-%dT%H:%M:%SZ' 2026-08-18T09:00:00Z +%s000)"

Note

One-shot tasks (--at or no schedule) run through the bare TaskStore and get a session lazily. Recurring tasks (--cron/--every) must boot the full runtime so they can allocate one persistent session reused across every firing.

Note

task tick drains what is due right now, once, and exits. Recurring tasks it runs are requeued for their next firing as usual. It does not keep running, so for continuous scheduling leave ATOMIC_AGENT_TASKS_SCHEDULER_ENABLED on (the default) with tui or serve running.

Trace — inspect & replay sessions

Traces are append-only NDJSON files, one per session, capturing turns, steps, prompts, LLM completions, and tool calls. The trace command reads and replays them.

atomic-agent trace list   [--limit N]
atomic-agent trace show    <sessionId> [--step N] [--raw]
atomic-agent trace export  <sessionId> [--format ndjson|json]
atomic-agent trace replay  <sessionId> [--step N]

Subcommand	Notes
list	Recent trace summaries.
show <sessionId>	Human-readable chronology. --step N isolates one step; --raw prints unformatted lines.
export <sessionId>	Dump as ndjson (default) or json.
replay <sessionId>	Rebuild the stable prefix with current tools/skills/capabilities and compare hashes to detect prompt drift. --step N isolates a step. Exits 0 if no drift, 2 if drift is detected.

Note

Tracing is on by default for run, tui and serve, and off for task commands and the sidecar (see Traces and replay). NDJSON lines are best-effort — malformed lines are silently skipped, so treat traces as diagnostics, not authoritative state. They are also unredacted (prompts and user messages verbatim); treat trace files as confidential.

Skill — manage skills

Skills are folders (a SKILL.md plus optional scripts) that extend the agent with reusable playbooks.

atomic-agent skill install <path|owner/repo[/path]|@owner/slug> [--force] [--acknowledge-risk]
atomic-agent skill uninstall <name>
atomic-agent skill list
atomic-agent skill show <name>
atomic-agent skill enable <name>
atomic-agent skill disable <name>
atomic-agent skill browse [--source owner/repo]
atomic-agent skill search <query>
atomic-agent skill tap list | add <owner/repo> | remove <owner/repo>

Subcommand	Notes
install <target>	Install from three kinds of source: a local directory path, a GitHub skill hub tap (owner/repo or owner/repo/path), or ClawHub (@owner/slug). --force overwrites an existing skill of the same name. --acknowledge-risk confirms you accept a remote skill flagged as suspicious by the install scan — without it, a flagged skill is refused.
uninstall <name>	Remove a global skill.
list	Show all skills with enabled/disabled state and source.
show <name>	Print the SKILL.md body.
enable / disable <name>	Toggle visibility by mutating skills.disabled in config.json. Disabled skills stay on disk but are invisible to the model.
browse [--source owner/repo]	List installable skills from ClawHub plus every configured GitHub tap. --source narrows it to a single tap.
search <query>	Search ClawHub and the configured taps by keyword.
tap list|add|remove	Manage the GitHub repositories browse and search read from. Mutates skills.taps in config.json. Ships with anthropics/skills, openai/skills, and vercel-labs/agent-skills.

Caution

A remote skill is somebody else’s code, and skills can carry runnable scripts. install scans a remote skill before writing it and refuses anything it flags; --acknowledge-risk is how you override that refusal. Read the SKILL.md and its scripts before you use it.

Tip

Project-local skills in ./.atomic-agent/skills/ shadow global ones of the same name. There is no merge or version comparison — the project version wins.

Models — local llama.cpp models

Manage the managed-mode local inference daemon: download backends and GGUF models, start/stop the server, and pick GPU devices. models search also looks up models on your configured cloud providers.

atomic-agent models list | status | devices
atomic-agent models pull <id> [--background] [--mmproj]
atomic-agent models downloads [cancel <id> | clear]
atomic-agent models use <id> | remove <id>
atomic-agent models start | stop | update
atomic-agent models use-device <auto|cpu|Vulkan0>
atomic-agent models list-embeddings
atomic-agent models pull-embedding <id> [--background]
atomic-agent models use-embedding <id> | --disable
atomic-agent models search <query> [--provider ID] [--limit N] [--json] [--refresh]

Group	Subcommands
Chat models	list, pull <id>, use <id>, remove <id>, status, update
Downloads	pull --background keeps downloading after the terminal closes; downloads lists background downloads, downloads cancel <id> stops one (the partial file is kept, and pull resumes it), downloads clear forgets finished records. pull --mmproj also fetches the vision projector.
Daemon	start, stop
GPU	devices, use-device <auto|cpu|Vulkan0>
Embeddings	list-embeddings, pull-embedding <id>, use-embedding <id> / --disable
Cloud	search <query> searches your configured cloud providers’ models by id, vendor, and capability (for example claude vision or free tools). --refresh pulls live model lists first. No local runtime needed.

Note

A fresh install starts in external mode with no active model — localModels.managed.modelId is null until you pull one. models use <id> sets the model and flips localModels.mode to managed, so you do not have to edit the mode by hand. The setup wizard suggests qwen-3.5-4b, but nothing is active until it is pulled.

Note

The chat daemon is primary — if it fails to start, that is fatal. The embedding daemon is optional: if it fails, chat still runs and memory recall falls back to FTS5-only (no embedding cosine re-rank).

Which subcommands need managed mode

Only start and update refuse to run in external mode (where you point at a llama-server you run yourself). use <id> switches you to managed mode. list, pull, remove, devices, and status work in either mode. The command’s own --help still says the whole group needs managed mode; that text is out of date.

Config — read & write config

Read and edit the user config file at <stateDir>/config.json, one key at a time or as a whole document.

atomic-agent config get                  # whole file as JSON
atomic-agent config get <key>            # one value, e.g. log.level
atomic-agent config set <key> <value>    # one value, rest of the file untouched
atomic-agent config set '<json>'         # replace the whole file (missing keys get defaults)
atomic-agent config unset <key>          # restore one key to its default
atomic-agent config list                 # every key as key = value
atomic-agent config path                 # where config.json lives

Keys are dotted paths such as log.level or agent.approvalLevel. Values are typed by the config schema, so false, 40 and info are written as a boolean, a number and a string. Bounds and enums are checked before anything is written.

atomic-agent config set log.level debug
atomic-agent config set agent.maxSteps 40
atomic-agent config unset log.level      # back to "info"

List-valued keys such as projects.roots have no single-value form. Set them with the whole-file JSON form; unset works on them.

config set '<json>' replaces the whole file

With a JSON argument, config set writes that JSON as the entire config file. Every key you leave out is reset to its default, including your LLM providers, MCP servers, and an analytics opt-out. To change one setting, use config set <key> <value> instead. If you do need the whole-file form, start from the current document:

atomic-agent config get > /tmp/config.json
# edit /tmp/config.json in your editor
atomic-agent config set "$(cat /tmp/config.json)"

Caution

The runtime freezes config at bootstrap. Editing config.json (by hand or via config set) does not affect an already-running process; the next launch picks it up. The TUI panels apply their own changes live. Do not use HTTP PATCH /api/config to change a setting: in v0.6.5 it resets most of the file (see the HTTP server page).

Memory: export the memory store

atomic-agent memory export [--vault PATH] [--folder NAME]

One-way export of the memory corpus (notes, lessons, procedures from <stateDir>/memory.sqlite) into an Obsidian vault, as Markdown files with YAML frontmatter and [[wikilinks]] along the memory’s own links.

Flag	Default	Description
--vault PATH	$OBSIDIAN_VAULT_PATH	An existing Obsidian vault directory.
--folder NAME	atomic-agent	The vault subfolder the export owns.

The export is idempotent: re-running it overwrites its own files in place and prunes files whose record is gone. Other files in the vault are never touched, and the database is opened read-only, so nothing syncs back.

Update: self-update the binary

atomic-agent update [--check | --version <tag>]

Checks GitHub Releases for a newer version and re-runs the install script in place, the same as the TUI’s in-app update. It only applies to the installed binary; a source checkout is updated with git. The running process is not restarted, so the new version takes effect on the next launch.

Flag	Description
--check	Report the current and latest version, install nothing.
--version <tag>	Install a specific release tag (for example v0.6.5) instead of the latest.

Exit codes: 0 up to date, updated, or check succeeded; 1 the check or the install failed, or this install cannot self-update; 2 usage error.

Uninstall: remove Atomic Agent

atomic-agent uninstall [--dry-run] [--keep-data] [--keep-binary] [--keep-path] [-y | --yes]

Deletes the state directory (config, memory, sessions, tasks, traces, and downloaded models), the installed binary and its atag alias, the asset folders installed beside them, and the PATH line the installer added to your shell rc file. Interactive runs list everything with sizes and ask you to type a confirmation word; non-interactive runs must pass --yes.

Flag	Description
--dry-run	Print exactly what would be removed, remove nothing.
--keep-data	Keep the state directory; remove only the program.
--keep-binary	Keep the binary; remove only the data.
--keep-path	Leave the installer’s PATH line in your rc file.
-y, --yes	Skip the typed confirmation (for scripts).

Danger

Uninstall cannot be undone and makes no backup. Run --dry-run first, and use --keep-data if you plan to reinstall and want to keep your memory and sessions.

Exit codes: 0 removed, dry run printed, or you declined; 1 something could not be removed; 2 usage error (unknown flag, or no terminal and no --yes).

REPL — debug REPL

atomic-agent repl

A minimal scaffold REPL for debugging. It is hidden from --help and is not a substitute for run or tui.

Import — migrate from another agent

Migrate from Claude Code, Codex, Hermes, OpenClaw, Pi or Oh-My-Pi into Atomic Agent. Imported sessions are prefixed with the source name (claude-code:, hermes:, and so on) so they never collide with native ones. What each source brings is listed in the Import guide.

Hermes

atomic-agent import hermes [--source DIR] [--preset default|full]
                           [--include a,b] [--exclude a,b]
                           [--migrate-secrets] [--limit N]
                           [--overwrite] [--dry-run] [--yes]

• --source defaults to ~/.hermes (or HERMES_STATE_DIR).
• --preset selects what to import (default = sessions + cron). --include / --exclude adjust it.
• --migrate-secrets is the only way to copy secrets, and is limited to an allowlist (OPENROUTER_API_KEY, AIMLAPI_API_KEY). Secrets are never part of a preset.

OpenClaw

atomic-agent import openclaw [--source DIR] [--agent NAME]
                             [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

• --source defaults to ~/.openclaw (or OPENCLAW_STATE_DIR).
• --agent picks which agent’s sessions to import (default main).
• --include / --exclude adjust what is imported (sessions, cron), same as for Hermes.

Claude Code / Codex

atomic-agent import claude-code [--source DIR] [--include a,b] [--exclude a,b]
                                [--migrate-secrets] [--limit N]
                                [--overwrite] [--dry-run] [--yes]
atomic-agent import codex       [--source DIR] [--include a,b] [--exclude a,b]
                                [--migrate-secrets] [--limit N]
                                [--overwrite] [--dry-run] [--yes]

• --source defaults to ~/.claude (or CLAUDE_CODE_STATE_DIR) and ~/.codex (or CODEX_STATE_DIR).
• Options: Claude Code skills, memory, mcp, sessions; Codex skills, memory (AGENTS.md), sessions. All are on by default.
• --migrate-secrets copies ANTHROPIC_API_KEY (Claude Code settings.json) or OPENAI_API_KEY (Codex auth.json).

Pi / Oh-My-Pi

atomic-agent import pi       [--source DIR] [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]
atomic-agent import oh-my-pi [--source DIR] [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

• --source defaults to ~/.pi/agent (or PI_STATE_DIR) and ~/.omp/agent (or OMP_STATE_DIR).
• Options: Pi skills, sessions; Oh-My-Pi skills, mcp, sessions. All are on by default.
• No key migration for either.

Flag	Description
--limit N	Cap the number of sessions processed (-1 = no limit).
--overwrite	Overwrite a differing destination instead of flagging it as a conflict.
--dry-run	Preview only — reconciliation runs but nothing is written.
--yes	Skip the interactive confirmation.

Tip

Import is idempotent on the source. Conflicts are detected structurally (the full transcript, not just the id), so re-running a non---overwrite import safely skips identical items and reports duplicates rather than corrupting state.

Environment variables

The CLI reads these at bootstrap. They cover operational and bootstrap values that have no config.json key; the file wins for user-facing settings like model and log level. Three exceptions override a file key for one process: ATOMIC_AGENT_LLAMA_MAX_TOKENS (over localModels.completionMaxTokens), ATOMIC_AGENT_SKILLS_CATALOG_BUDGET (over skills.catalogTokenBudget), and ATOMIC_AGENT_DOWNLOAD_CONNECTIONS (over localModels.download.connections).

Variable	Purpose
ATOMIC_AGENT_STATE_DIR	Root for state: config.json, traces, tasks.sqlite, memory, skills. Defaults to ~/.atomic-agent.
ATOMIC_AGENT_LLAMA_API_KEY	Bearer token for llama-server (optional).
ATOMIC_AGENT_LLAMA_MAX_TOKENS	Overrides localModels.completionMaxTokens (default 16384) for this process, clamped 64 to 131072. The CLI’s --help still says 8192; that text is out of date.
ATOMIC_AGENT_API_KEY	Bearer token for the serve HTTP API (fallback when --api-key is omitted).
ATOMIC_AGENT_RG_PATH	Override the bundled ripgrep binary path.
ATOMIC_AGENT_BROWSER_CHANNEL	chrome | msedge | chromium (default chrome).
ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH	Explicit Chromium binary path (overrides auto-detect).
ATOMIC_AGENT_BROWSER_HEADLESS	1 for headless mode (default 0).
ATOMIC_AGENT_BROWSER_NO_SANDBOX	1 to pass --no-sandbox (containers/CI only).
ATOMIC_AGENT_BROWSER_CDP_URL	Attach to an existing browser via Chrome DevTools Protocol.
ATOMIC_AGENT_DEBUG_ARGV	1 logs process.argv to stderr.
ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP	Check for a newer release at startup (default true).

Task queue

The task queue is configured only through environment variables — there is no tasks block in config.json.

Variable	Default	Purpose
ATOMIC_AGENT_TASKS_ENABLED	true	Master switch for the durable task queue.
ATOMIC_AGENT_TASKS_MAX_ATTEMPTS	3	Default retry budget per task.
ATOMIC_AGENT_TASKS_RUN_ON_CREATE	true	Run a task immediately when it is created with no schedule.
ATOMIC_AGENT_TASKS_SCHEDULER_ENABLED	true	Run the long-lived background scheduler.
ATOMIC_AGENT_TASKS_SCHEDULER_TICK_MS	5000	Scheduler poll interval.
ATOMIC_AGENT_TASKS_MIN_INTERVAL_MS	1000	Floor on --every intervals.

There are many more ATOMIC_AGENT_* tuning vars for the agent loop, tasks, and memory. See the Configuration reference for the full list.

Common config keys

These live in <stateDir>/config.json and back the flags above. Change one with atomic-agent config set <key> <value>, or use the TUI.

Key	Default	Description
localModels.mode	external	managed runs the daemon; external expects a llama-server you run yourself. models use <id> flips this to managed.
localModels.url	http://127.0.0.1:8080	HTTP URL for the llama-server API in external mode. In managed mode the URL is http://127.0.0.1:<localModels.managed.port>.
localModels.managed.modelId	null	Active model id in managed mode. Nothing is active until you pull a model.
localModels.managed.port	19091	Port for the managed chat daemon (embeddings use 19092).
localModels.completionMaxTokens	16384	Max new tokens per completion. 0 means no client-side cap.
agent.maxSteps	25	Steps per leg. After a leg the agent reports progress and continues, while agent.task.autoContinue is on.
agent.task.maxSteps	1000	Hard step ceiling for one task. --max-steps overrides it.
agent.task.maxDurationMs	7200000	Wall-clock ceiling for one task (2 hours).
agent.task.autoContinue	true	Continue into the next leg automatically instead of stopping after agent.maxSteps.
agent.tokenBudget	3000	Max prompt tokens per turn.
agent.approvalLevel	1	Approval ladder, 1 to 5. See below. --no-approval forces 5 for one process.
log.level	info	debug | info | warn | error.

The approval ladder

agent.approvalLevel replaced the old boolean agent.approvalRequired in schema v37. It is a 1–5 ladder and each level is cumulative — it stops asking about everything the level below it stopped asking about.

Level	Name	Stops asking about
1	paranoid	Nothing — every gated action asks first. This is the default.
2	workspace	File writes, edits, and patches strictly inside the session working directory.
3	home	Adds file writes anywhere under your home directory, moves to Trash, archive extraction, and HTTP requests.
4	operator	Adds guarded shell commands, skill scripts, process kills, network git (push, pull, fetch, clone, adding a remote), publishing (PRs, issues), and Fusion fan-out.
5	full trust	Everything, including browser navigation to non-web URLs, writes to the agent’s own trust config, reads outside the working directory, and sending email.

Hardline shell-guard rules sit outside the ladder and block at every level.

Note

If your config.json still has a legacy agent.approvalRequired, it is migrated on read: false maps to level 5, true (or absent) maps to level 1. The legacy key is never written back.

Where to go next

Configuration

The full config.json schema, every environment variable, and precedence rules.

HTTP API

Request/response shapes for serve, including streaming chat completions and the approval SSE stream.

Tasks & scheduling

Schedule syntax (--at / --cron / --every), retry behavior, and session binding.

Skills

The SKILL.md format, script allowlisting, and the approval gate for skill.run_script.