atomic-agent

Use the CLI for simple sessions, automation, and debugging. Use the TUI for an interactive control console: approvals, logs, models, skills, tasks, memory, MCP, channels, and traces.

atomic-agent run --cwd /path/to/work
atomic-agent tui --cwd /path/to/work
atomic-agent skill list
atomic-agent task list
atomic-agent trace list --limit 10

Context. The chip at the right of the composer shows the transcript against its ceiling and the model's window. History is limited in tasks, not tokens: one task is a thing you asked plus everything the agent did answering it, and agent.conversationMaxPairs (1-1000, default 200) sets how many the prompt carries. Click the chip or run /context to change the count and see the cost before you send.

Switch modes with /mode, ctrl+g M, or the composer chip. On an approval prompt, ctrl+y approves, ctrl+d denies, ctrl+f grants the category, ctrl+b retargets a write or grants a shell command's shape, ctrl+z pages through the full command when the preview is cut, esc aborts, and typing answers the agent in words. /theme switches between six palettes: classic-dark, classic-light, toxic-green, khorne-red, darky-dark, moon-yellow. The TUI is clickable; to select text, drag over plain text, or turn the mouse off with /mouse off or --no-mouse. Handy slash commands: /help, /tools, /model, /privacy. A failed or long turn raises a desktop notification, sessions are named from their first prompt, and inside a herdr pane the TUI labels the pane with its state.

Full TUI guide: TUI.md.

local and cloud are the two routes the composer always offered. Fusion adds a third: one model orchestrates and a pool of workers executes the parts it delegates. The usual pairing is a cloud orchestrator with local llama-server workers, but neither leg is tied to a kind: a local model can plan for cloud workers, and /runmode swap trades the two legs. The only rule is that the legs are two different providers. The block is additive and llm.activeTextProvider stays authoritative:

"llm": {
  "activeTextProvider": "openrouter",
  "runMode": {
    "mode": "fusion",
    "fusion": { "orchestratorProvider": "openrouter", "workerProvider": "local-llama", "workers": 3 }
  }
},
"localModels": { "managed": { "parallel": 3 } }

workers (1..8, default 2) is the default fan-out width when the orchestrator does not name one; it is not a ceiling, and the orchestrator can ask for more on a given call. What bounds the width on a local leg is localModels.managed.parallel, the llama-server --parallel slot count (default "auto", sized from the daemon's context; a number pins it; applied on the next daemon start). On a cloud worker leg the width is capped by cloudWorkers (1..32, default 4). The orchestrator model is the provider's defaultChatModel; on a local leg the worker model is the one the managed daemon serves. reviewStallSteps (default 6, 0 disables) nudges an orchestrator that keeps reading instead of delegating or replying.

In the TUI, fusion is the last row of the composer's Where it runs switch (ctrl+r, or click the backend word): it needs two providers that can answer, one per leg, and says which one is missing otherwise. While it is on, the backend word is an orange chip and the composer and the chat bubbles take the same tint. /runmode local|cloud|fusion and ctrl+g 1/2/3 pick a mode from the keyboard; /runmode swap trades the orchestrator and worker legs; /runmode status says what the mode resolves to.

On the fusion route the strip gains a fourth control, Workers (→ past the model, or click the worker count): it picks the worker model and the default fan-out width, and /runmode workers N does the same from the keyboard. The provider and model controls address the orchestrator leg. On a local worker leg the worker count also sets localModels.managed.parallel, so restart the local daemon to apply it. Once fusion is on, the orchestrator gains one tool, fusion.delegate, and prompt guidance telling it to plan first and hand the independent bulk down: reading many files, first drafts, boilerplate, tests, wide searches. Each part it delegates runs as its own throwaway worker turn (several at a time), and their replies come back into the same call for the orchestrator to check and merge; you see each worker start and finish in the chat feed. The orchestrator itself does not run mutating tools. Workers cannot delegate further, cannot reach you, and cannot schedule tasks or write memory. Approving a fan-out lets its workers write and run commands inside the directories it names; anything outside them comes back as a named path, and the orchestrator sends the task out again with that path so you can approve the wider scope.

The CLI can manage a paired llama.cpp setup for chat and embeddings:

atomic-agent models update
atomic-agent models list
atomic-agent models pull qwen-3.5-4b
atomic-agent models use qwen-3.5-4b

atomic-agent models list-embeddings
atomic-agent models pull-embedding <model>
atomic-agent models use-embedding <model>

atomic-agent models start

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

Managed mode downloads the backend, pulls GGUF models, selects the active model, and starts detached chat / embedding daemons when configured.

The default engine is Atomic Chat Core, which installs and runs our TurboQuant llama.cpp build for your computer. The first start installs it with progress. If that fails, the error says what happened and how to retry: atomic-agent models update (TUI: R in Models). The standalone llama.cpp server remains a support-only fallback that the app does not show: atomic-agent models engine llama-server selects it and atomic-agent models engine atomic-core switches back; both engines use the same model files.

embeddinggemma-2 (Google's EmbeddingGemma 2, multilingual, 768-dim) runs only on the Atomic Core engine: Core serves it from its embedding module and the first models start-embedding installs the newer stock llama.cpp build it needs.

Big models can download in the background, detached from the terminal that started them:

atomic-agent models pull --background qwen-3.5-35b   # returns at once; keeps running after the terminal closes
atomic-agent models downloads                        # list background downloads, progress, interrupted ones
atomic-agent models pull qwen-3.5-35b                # follow a running download in the foreground (Ctrl+C detaches)
atomic-agent models downloads cancel qwen-3.5-35b    # stop it; what was fetched stays on disk

The TUI runs every model download through the same worker. Quit mid-download (Ctrl+C, closing the window) and the download continues; open the TUI again and the chip picks it up where it is, and when the file lands the model is activated and the daemon started as if you had waited. A worker that died mid-way is resumed automatically on the next launch; one you cancelled is not. On the LLM tab's Local pane, x stops the download in flight and keeps what it fetched, and Enter on the row resumes it.

The worker is a detached copy of the CLI writing its progress to <stateDir>/models/downloads/<job>.json and its log next to it, the same arrangement as the managed llama-server daemon. A worker that dies mid-way (a reboot, a kill -9) shows as interrupted in models downloads, and running the same pull again, with or without --background, resumes from the partial file. pull --mmproj also fetches a vision model's projector; pull-embedding --background works the same way for embedding models.

Model downloads resume. An interrupted pull (a dropped connection, Ctrl+C, a closed terminal) keeps what it has fetched next to the destination as <file>.part, and the next models pull of the same model continues from that point with a Range request rather than starting over. The downloader validates the partial against the server's ETag before appending, so a file re-uploaded under the same name is fetched afresh; within one pull, transport errors and stalls retry from the partial with backoff before giving up.

The managed chat daemon stops when the last session exits, freeing the RAM and VRAM the model was holding; set localModels.managed.stopOnExit: false in config.json to keep the model warm between sessions. Daemons started standalone with models start are never touched.

On Windows the backend zip is picked per machine (the CUDA 12.4 build when the NVIDIA driver supports CUDA 12.4 or newer, Vulkan on RTX 50-series cards and everywhere else). If the GPU build cannot serve a model on your hardware (typical for iGPU-only boxes), the start falls back to the CPU build automatically and records localModels.managed.backendVariant: "cpu" in config.json; set it to "auto", "vulkan", "cuda-12.4" or "cuda-13.3" to pick a build yourself (for example after a driver update; the CUDA 13.3 build currently needs the CUDA Toolkit installed).

On Linux arm64 there is a single build and it is used on every machine. It bundles the CUDA runtime and cuBLAS for the NVIDIA GB10 superchip in DGX Spark, and it also carries the dispatched CPU backends (armv8.0 through armv9.2); the GPU backend is loaded at runtime, so a box with no NVIDIA driver runs the same build on its CPU. That bundle makes the download large, ~554 MB against ~30 MB on x64. It needs glibc 2.38 or newer (Ubuntu 24.04, Debian 13, DGX OS 7); on an older or musl system managed mode says so before downloading anything and external mode is the way to run.

Cloud models are searchable from the same command: by id, vendor, or capability, across every configured cloud provider:

atomic-agent models search claude vision
atomic-agent models search free tools --json
atomic-agent models search "1m cache" --provider openrouter --limit 10
atomic-agent models search kimi --refresh   # pull live /models lists first

Every term has to match (claude vision is not a substring of any id), a size term names a whole-unit bucket whatever the row displays (1m finds windows from 1M up to 2M, including the 1,048,576-token ones that render as 1.0M; a 2M window answers to 2m; 128k finds 131,072), results are ranked best-first, and the same query works in the TUI Cloud pane (press f). If --refresh cannot load a live OpenRouter or AI/ML API list, the search answers from the bundled list and prints one warning: line on stderr with the provider, the reason (network error, timeout, HTTP status, a body that is not JSON) and how long the attempt took.

Already have your own llama.cpp process? Point atomic-agent at it with localModels.url in <stateDir>/config.json (external mode; the default is http://127.0.0.1:9931, llama-server's own default port since llama.cpp v0.7.0), or save the URL in the TUI's LLM tab, External pane:

// <stateDir>/config.json
{
  "localModels": { "mode": "external", "url": "http://127.0.0.1:8080" }
}

./llama-server -m Qwen3.5-9B-Q4_K_M.gguf \
  --slots 4 \
  --parallel 4 \
  --port 8080 \
  --cache-reuse 256

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

The LLM tab in the TUI has an External pane for this setup. Saving a URL runs an honest health probe: it validates the /health body, reports llama.cpp's 503 answer while a model loads as loading rather than dead, and recognizes when the URL is a different OpenAI-compatible runner that should be added as a cloud provider instead.

Running models under Ollama, LM Studio or Atomic Chat? All three are OpenAI-compatible servers, and all three are presets in the provider wizard, so there is no base URL to type.

ollama serve
ollama pull qwen2.5:0.5b

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

In the TUI, open the LLM tab, add a provider, and pick Ollama (local) (or LM Studio (local), Atomic Chat (local)). A local server has no API key, so the wizard skips the key screen and goes straight to the model choice: two screens, service then model.

Model ids are the tags the server reports, qwen2.5:0.5b or llama3.2:latest for Ollama, so use the same name you passed to ollama pull. The list comes from the server's own /v1/models, which means anything you have pulled shows up without a restart.

The preset is a fixed http://localhost:11434 endpoint; it does not probe for a running server. If ollama serve isn't up when you reach the model step, the list fails to load (could not list models from Ollama (local)), and the wizard falls back to letting you type a model id by hand; in the LLM panel the list shows model list unavailable and only the current model. Start the server (ollama serve, then ollama pull <model> for anything you want) and re-open the preset.

For Atomic Chat, the endpoint is the desktop app's Local API Server (Settings › Local API Server). The app only raises it while a model is loaded, so start a model first or the model list will not load. It needs no key unless you set one in those settings; if you did, put the same value in ATOMIC_CHAT_API_KEY in the state dir's .env. An External llama.cpp URL on :1337 is recognized and offered this preset, the same way :11434 is offered Ollama.

Two things to know. Ollama's OpenAI-compatible surface lives under /v1, but the base URL is stored without it, since every call site appends /v1/... itself. And Ollama (local) is a different entry from Ollama Cloud: the first is the server on your machine and needs no key, the second is the hosted endpoint.

Tool calling works over this path, so the agent loop runs normally, but it is only as reliable as the model you picked. Very small models emit malformed tool calls more often; if the loop stalls, try a larger one before assuming the provider is at fault.

Run atomic-agent as a local HTTP service:

atomic-agent serve \
  --host 127.0.0.1 \
  --port 8787 \
  --cwd /path/to/work \
  --api-key "$ATOMIC_AGENT_API_KEY"

Without a key, anyone who reaches the port can run the agent and its tools, so serve refuses to start on a host other than loopback (0.0.0.0, a LAN address) unless --api-key or ATOMIC_AGENT_API_KEY is set. On loopback it still starts without one and prints a one-line warning.

POST /v1/chat/completions maps one request to one full macro-turn: user -> 0..N tool steps -> reply. Atomic-specific routes expose sessions, approvals, tasks, webhooks, events, skills, config, and capabilities.

serve boots the same runtime the TUI does, so enabled Telegram and Discord bots, and every enabled Swarm bot that has a token, come up in this process too. That makes serve the way to keep the bots answering with no TUI open; it stays in the foreground until you stop it and does not restart itself. Each bot runs in one process at a time; see Channels below.

serve does not outlive whoever started it. When the process that started it goes away, the server finishes any turn still running and then shuts down, the same way it would on SIGTERM — so a killed editor, a crashed desktop app or a closed test harness cannot strand a server that holds its port and its database handles for weeks.

To daemonise it, pass --no-parent-exit (or set ATOMIC_AGENT_SERVE_NO_PARENT_EXIT=1). That is the supported way to run serve in the background from a shell — including under nohup and with & disown, neither of which detaches the process from the shell, so neither survives on its own. A serve started with no parent at all, as under launchd or systemd, needs no flag.

Each server records itself under <stateDir>/serve/ and sweeps strays left by earlier runs; atomic-agent serve --reap does the same sweep by hand and prints what it found. The sweep signals a process only when it has positive evidence the server was abandoned — the exact process that started it is gone — and /health on the recorded port identifies it as that same atomic-agent, reparented and idle. A server marked as a daemon is never touched, no matter how long it runs; anything still working, and anything the sweep cannot confirm, is left alone and keeps its record.

The sidecar speaks newline-delimited JSON over stdio, making it easy to embed in desktop apps:

{"kind":"request","id":"r-1","type":"start_session","payload":{"workingDir":"/home/me"}}
{"kind":"request","id":"r-2","type":"send_message","payload":{"sessionId":"s-1","text":"Check the inbox and summarize urgent mail."}}

Events stream back as the turn runs:

{"kind":"event","id":"e-1","type":"turn_started","correlationId":"r-2","payload":{"sessionId":"s-1","turnIndex":0}}
{"kind":"event","id":"e-2","type":"tool_call_result","correlationId":"r-2","payload":{"sessionId":"s-1","stepIndex":0,"tool":"browser.read_aria","status":"ok","summary":"url: https://mail.google.com/ ..."}}
{"kind":"event","id":"e-3","type":"assistant_reply","correlationId":"r-2","payload":{"sessionId":"s-1","text":"You have 3 urgent threads."}}

Drive the same agent from a Telegram or Discord bot. Tokens live in <stateDir>/.env, never in config.json:

// <stateDir>/config.json
{
  "telegram": { "enabled": true, "ownerUserId": null },
  "discord":  { "enabled": true, "ownerUserIds": ["123456789012345678"] }
}

# <stateDir>/.env
TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token
DISCORD_BOT_TOKEN=your-discord-bot-token

Both can be set up from the Integrations tab in the TUI. Each bot answers only its owner: in a DM, or in a group or server channel when you @mention it or reply to it. Every chat, forum topic, Discord channel and thread gets its own session, and both bots understand /status, /sessions, /switch <id>, /new, /model [provider] [model-id] and /cancel. Approvals arrive as buttons in the chat the turn came from; only an owner can press them. Messages and files pass through Telegram's or Discord's servers.

Channels belong to the runtime, not to the TUI: atomic-agent serve boots them the same way, so the bots keep answering with no terminal UI open. Each bot is guarded by its own lockfile in the state dir; a second process that tries to start the same bot leaves it down with already running in another atomic-agent (pid N) and does not retry, so start bots from serve or from the TUI, not from both.

Telegram. Pair from the TUI (p in Integrations, or /telegram pair): it shows a one-time 6-digit code, and the account that sends the bot /start <code> within 5 minutes becomes the owner; any other message is ignored. Replacing an existing owner asks you to confirm first, and after pairing the TUI names the new owner's @username. In groups, turn off the bot's privacy mode in @BotFather, or plain @mentions are not delivered to it. While a turn runs, the bot keeps one silent progress bubble updated with step labels only, never tool output; turn it off with "telegram": { "progressIndicator": false }. Files you send in the DM are saved under <stateDir>/inbox/telegram/, one folder per day, and the agent gets the path with your caption (albums arrive as one message; Telegram lets bots fetch up to 20 MB). Files the agent attaches to a reply follow the text, images inline and the rest as documents, up to Telegram's 50 MB bot limit. Scheduled tasks can report back: atomic-agent task create --cron "0 9 * * *" --message "morning digest" --notify telegram (or notify: "telegram" when the agent schedules it) posts each run's result to your paired DM. Reporting is per task, Telegram only; if the channel is down the report is skipped with a logged warning.

Discord. There is no pairing: put your user id (as a string) in ownerUserIds; an empty list refuses every message. The bot needs no privileged intents, because Discord delivers DMs and @mentions without them. Inbound files up to 50 MB go to <stateDir>/inbox/discord/; reply attachments are uploaded one message each, within your server's upload limit. There is no progress bubble.

Swarm. Run extra Telegram or Discord bots beside the two above, each with its own token, owner, lockfile and sessions. Manage them in the Swarm tab (/swarm), which writes swarm.units and the token for you:

"swarm": { "units": [
  { "id": "ops", "kind": "telegram", "label": "Ops", "role": "on-call triage",
    "enabled": true, "tokenEnv": "TELEGRAM_BOT_TOKEN_OPS", "ownerUserId": null }
] }

The Swarm tab names the token key <KIND>_BOT_TOKEN_<ID>. Each unit has one owner; Telegram units pair from the Swarm tab, Discord units take the id directly. role is a free-text note shown in the tab and does not change what the bot does.

Composio is a hosted catalogue of 1500+ SaaS toolkits (Gmail, Slack, Notion, Linear, and more) that also brokers each app's OAuth, so you never register an OAuth client yourself.

Open the Integrations tab in the TUI and follow the setup, or drop a key into <stateDir>/.env:

COMPOSIO_API_KEY=ck-your-key

The key is the real gate: with no key the runtime opens no connection and registers no tool. Set "composio": { "enabled": false } in config.json to keep the key on disk with the toolkits off.

Under the hood this is not a new subsystem. Composio's tool router speaks Streamable HTTP MCP and authenticates with a static header, which is exactly the transport the MCP client already supports, so the agent treats it as one more MCP server. Tools land as mcp.composio.*.

Rather than loading 1500 toolkits into the prompt, the session exposes four meta-tools: the agent searches for a tool by use case, fetches its schema, then executes. Discovery is annotated read-only and flows without prompting; COMPOSIO_MULTI_EXECUTE_TOOL and COMPOSIO_MANAGE_CONNECTIONS are marked destructive, so every write to a real account still hits the approval gate.

Connected accounts are scoped by a random install id minted once and stored in config.json, never your email. Losing it means re-authorising every connected app.

Note that Composio is a hosted service: your OAuth tokens for connected apps live on Composio's infrastructure, and tool calls are executed through their servers rather than from your machine.

Configure MCP servers in config.json, and their tools join the same registry as local tools. Trusted read-only servers can batch with other reads; untrusted servers default to approval-gated execution.

{
  "mcp": {
    "servers": [
      {
        "name": "docs",
        "enabled": true,
        "transport": {
          "kind": "stdio",
          "command": "npx",
          "args": ["-y", "@example/mcp-server"]
        },
        "trust": "pure_read"
      }
    ]
  }
}

To offer only some of a server's tools, list their raw names: "enabledTools": ["get_issue", "list_issues"] keeps just those, and "disabledTools": ["delete_repository"] drops tools on top of that (or on its own, from the full list). Turned-off tools never reach the prompt and cannot be called; a change applies when the server reconnects.

The TUI MCP panel supports live add / remove without restarting the process. When a stdio server fails to connect, the tail of its stderr is surfaced in the error instead of a bare disconnect message.

• Node.js for development; release bundles ship as Node SEA binaries.
• A reachable llama-server, either managed by atomic-agent models or launched externally.
• Managed mode picks the GPU backend automatically: Metal on Apple Silicon, CUDA on Windows when nvidia-smi reports a supported driver (including the reworked driver 610+ headers) with Vulkan as the fallback, Vulkan on Linux, a single CUDA-enabled build on Linux arm64 (tuned for the NVIDIA GB10 in DGX Spark) that uses the GPU when an NVIDIA driver is present and the CPU otherwise, CPU when no GPU is usable.
• Chrome, Microsoft Edge, or another configured Chromium-family executable. Browser binaries are not bundled.
• git for git tools.
• macOS workflows may need Accessibility, Screen Recording, Automation, or Reminders permissions.

Linux notes:

• Desktop tools (install via your package manager): ripgrep (file search; bundled binary used when present), xclip/xsel (X11) or wl-clipboard (Wayland) for clipboard, libnotify-bin for notifications, wmctrl for window control (X11/XWayland only), gio (glib2) or trash-cli for fs.trash.
• Browser: Chromium-family sandboxing can fail under some Linux setups (containers, certain kernels). If Chrome refuses to launch, set ATOMIC_AGENT_BROWSER_NO_SANDBOX=1 so the agent starts it with --no-sandbox (containers and CI only).
• GPU acceleration (managed mode): the backend always starts and falls back to CPU when no GPU driver is available. For GPU offload install a Vulkan driver. Intel/AMD: mesa-vulkan-drivers (+ vulkan-loader/libvulkan1); NVIDIA: the stock proprietary driver bundles its Vulkan ICD. Device auto-selected at start; override with atomic-agent models use-device <auto|cpu|Vulkan0>, inspect with atomic-agent models devices, or press G on the TUI LLM tab's Local pane. Multi-GPU: set localModels.managed.tensorSplit in config.json (e.g. [3, 1] for a 75%/25% layer split) to launch llama-server with --split-mode layer --tensor-split across every visible GPU; combine with use-device Vulkan0,Vulkan1 to restrict which devices join the split.

Cloud models are uncapped by default: the service applies the model's own maximum, so one turn can write a whole file. To bound it (spend, or a service that requires the field) set maxOutputTokens on the provider entry:

"llm": { "providers": [{ "id": "openrouter", "kind": "openrouter", "maxOutputTokens": 64000 }] }

Reasoning models spend that same budget on thinking, so a low ceiling can be used up before any answer appears.

Local models use localModels.completionMaxTokens (llama.cpp's n_predict, default 16384). Set it to 0 in config.json for no cap; generation then stops at a stop token or when the context window fills. That knob bounds time and runaway loops, not memory: what your machine commits is decided at daemon start by the model and --ctx-size, and does not grow with the length of one reply.

If a small local model keeps repeating itself, localModels.drySampler: true turns on llama.cpp's DRY anti-repeat sampler (it looks at the last 256 tokens of prompt plus reply) for every /completion request (Atomic Core or llama-server only; off by default, not yet measured on our task set).

Some models call tools reliably only when the provider constrains decoding to the tool's schema: OpenAI's strict mode. Set strictTools on the provider entry to send every function as strict:

"llm": { "providers": [{ "id": "mercury", "kind": "openai-compatible", "strictTools": true }] }

Off by default, and only for OpenAI-compatible kinds (openai-compatible, qwen-openai-compatible, openrouter, aimlapi, gemini). strict is a field on each tool, so extraBody cannot reach it; tools is a reserved key that is re-applied after that merge.

With the flag on, every tool schema is rewritten into the subset strict mode accepts: objects are closed, every property is listed in required (an optional one becomes nullable instead of being omitted), and value-range keywords the runtime validators enforce anyway (minItems, minLength, pattern, format, default, …) are stripped. A handful of tools take a free-form map (os.http.request's headers and body, mcp.prompt.get's arguments), and those cannot be expressed strictly; they are sent unconstrained (strict: false) rather than silently losing their arguments.

Because optionals become nullable, a strict model sends "pinned": null where it used to omit the key; on these providers a top-level null argument is dropped again before the call runs, so tools that check for presence behave as they always did.

The flag also sends parallel_tool_calls: false. Strict decoding and parallel calls do not compose (OpenAI's guidance is that a parallel call "may not match supplied schemas"), so a provider asked for strict tools is asked for one call per response. agent.maxParallelToolCalls still governs how the runtime executes a batch.

Turn it on only for a service that implements strict mode: one that does not will reject the whole request, not just the field.

OpenRouter serves most models from several hosts and picks one per request. To steer that (pin a host, forbid fallbacks, skip hosts that keep your data), set providerPreferences on an openrouter entry. It is sent unchanged as the request's provider routing object:

"llm": { "providers": [{ "id": "openrouter", "kind": "openrouter", "providerPreferences": { "order": ["z-ai"], "allow_fallbacks": false } }] }

It applies to every chat completion the entry makes (turns, memory sub-calls and vision.describe), and other kinds ignore it. The pre-save key check does not send it: that check asks the cheapest paid model for one token, and a host pinned for your model may not serve that one. If you already set extraBody.provider, that keeps winning.

User-facing configuration lives in <stateDir>/config.json.

Useful environment variables:

• ATOMIC_AGENT_STATE_DIR: state, config, skills, browser profile, memory, tasks, traces. Default: ~/.atomic-agent.
• ATOMIC_AGENT_LLAMA_API_KEY: optional bearer token for llama-server. It does not apply to Atomic Core: Core issues and rotates its own key, and the agent reads it from Core, so there is nothing to set. With the legacy managed llama-server engine the daemon is launched with this key; when it is unset, a key is generated once and kept in <models dir>/llama-server.key (mode 0600), so a web page in a local browser cannot call the daemon. The same key is used in external mode when localModels.url points at the managed port. Anything else that calls the managed daemon directly (scripts, other apps) must send Authorization: Bearer <key> with that key.
• ATOMIC_AGENT_LLAMA_MAX_TOKENS: completion cap, clamped to 64-131072.
• ATOMIC_AGENT_BROWSER_CHANNEL: chrome, msedge, or chromium.
• ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH: explicit Chromium-family executable path.
• ATOMIC_AGENT_BROWSER_CDP_URL: attach to an already-running browser via CDP.
• ATOMIC_AGENT_BROWSER_HEADLESS: 1 to run the browser headless.
• ATOMIC_AGENT_BROWSER_NO_SANDBOX: 1 to launch the browser with --no-sandbox (containers and CI only).
• ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP: false to skip the TUI's update check.

The external llama-server URL is set in config.json (localModels.url), not through the environment.

Secrets for skills and channels belong in <stateDir>/.env, not in config.json:

NOTION_API_KEY=ntn_xxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxx
TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token
EXA_API_KEY=exa_xxxxxxxx
OBSIDIAN_VAULT_PATH=/Users/me/Documents/Obsidian Vault

Shell-exported variables win over .env. The built-in parser intentionally supports only simple KEY=VALUE lines.

Commands the agent runs (os.shell.run, os.git.*, skill scripts) do not inherit these secrets: every variable named like a key, token, secret or password, and every known provider key, is removed from the command's environment, so a command slipped in through a web page or a file cannot read OPENAI_API_KEY or TELEGRAM_BOT_TOKEN. The agent itself still uses them. The names in tools.shell.envPassthrough in config.json are passed to shell commands anyway; the default is ["GITHUB_TOKEN", "NOTION_API_KEY"], which the bundled github and notion skills read through the shell. Add a name there when a command of yours needs one, or set [] to keep those two out as well. Reading the files themselves asks too: an agent tool reading .env, config.json or the local server key in the state folder, or a shell command that names one (cat ~/.atomic-agent/.env, sed -i … config.json), asks for approval at every level below 5, even where shell commands otherwise run unasked, and "allow for this session" is never offered for it. The shell check reads the command line for those paths; a command that builds the path at run time is not caught, so it is a guard, not a sandbox.

EXA_API_KEY is optional. Without it, web search uses Exa's free keyless tier, which runs out quickly, and then DuckDuckGo. When the free limit is reached, or no search provider answers, the search result says so and asks for a free key from https://dashboard.exa.ai/api-keys. Apps get the same request as details.keyRequired on the os.web.search result ({ provider: "exa", reason: "rate_limited" | "unreachable" | "missing", getKeyUrl, envVar }); the HTTP stream forwards it as key_required on the tool_result event. In the TUI, the Web search (Exa) entry of the Integrations tab saves the key (as EXA_API_KEY), and the next search uses it without a restart; the search error there points at /integrations instead of the .env file. The entry always writes EXA_API_KEY: when web.search.exa.apiKeyEnv names another variable, or Exa is neither web.search.provider nor in web.search.fallback, it says the key will not be used, and the search advice falls back to the .env file. A search site that cannot be reached from your network (DNS, refused, no answer to the connection within 5 s) is skipped by the searches that start after the failure, for two minutes, instead of each of them waiting for it again. That skip lives only in the running agent, and when every search site was unreachable the first site is tried again at most every 30 s.

The Integrations tab (/integrations) writes these for you. Its GitHub entry stores GITHUB_TOKEN and carries the Remote sync switch (git.remoteSync, off by default): while it is off, a repository the agent versions stays on this machine (git push, fetch, pull, clone and remote add are refused, through the git tools and through the shell alike), so you keep full local history without publishing anything. Turn it on when a project should reach GitHub; every sync then goes through the approval ladder. The dedicated tools (os.git.remote, fetch, pull, push, clone) honour the same switch and hand the token to git only for github.com, only through the child process's environment (never in a URL, in argv, or in .git/config) and scrub it from every line of output.

Drives a vendor CLI you are already signed into, so a flat-rate subscription can power the agent with no API key and no per-token billing. Two are supported: claude (Claude Code) and codex (OpenAI Codex).

Prerequisite: the CLI installed and signed in: claude then /login, or npm i -g @openai/codex then codex login. Atomic only spawns the binary; it never reads, copies, or replays its OAuth tokens or keychain entries.

In the TUI: Providers → n → pick the subscription row, then type a model. For Claude that is sonnet, opus, haiku, fable, or a pinned id like claude-sonnet-5; for Codex leave it blank: under a ChatGPT login Codex rejects explicit model ids (not supported when using Codex with a ChatGPT account) and resolves one itself. There is no API-key screen, because there is no key. Equivalent config.json:

{
  "llm": {
    "activeTextProvider": "claude-cli",
    "providers": [
      {
        "id": "claude-cli",
        "kind": "subscription-cli",
        "defaultChatModel": "sonnet",
        "subscriptionCli": { "cli": "claude" }
      }
    ]
  }
}

Optional keys inside subscriptionCli: binPath (absolute path when the CLI is not on PATH), extraArgs (appended verbatim, for example ["--effort", "high"]), streaming (set false to buffer), maxBudgetUsd.

Swap "cli": "claude" for "cli": "codex" to drive Codex instead, and drop defaultChatModel.

Each completion spawns the CLI fresh with the prompt on stdin (a two-zone prompt exceeds the 128 KiB argv limit). For claude it runs claude --print with these flags, which are load-bearing rather than cosmetic:

• --tools "": disables Claude Code's own Bash/Edit/Write. Without it a second agent would act on your machine outside Atomic's approval ladder.
• --strict-mcp-config with no config: keeps your MCP servers out of what should be a stateless completion.
• --system-prompt: replaces Claude Code's coding-agent prompt, which would otherwise compete with the prompt Atomic already built.
• --no-session-persistence: Atomic owns session state; CLI-side history would double-count context.
• --bare is never passed. Its own docs say OAuth and keychain are never read under it, which would defeat the whole feature.

For codex it runs codex exec --json with --ephemeral, --skip-git-repo-check, --ignore-user-config and -s read-only. Three differences are worth knowing, because Codex is a more opinionated agent than Claude's headless mode:

• There is no --tools "" equivalent. -s read-only confines Codex's own tools to reading; it cannot remove them. Left to itself, Codex will try to perform the request with its own tools instead of emitting Atomic's tool-call protocol; in testing it answered "I can't find probe.txt" after looking in its own working directory. The fix is an explicit completion-engine instruction prepended to the prompt (Codex has no system-prompt flag). It works (verified turns drive os.fs.read → reply and os.fs.read → os.fs.write → reply with no parse retries), but it is a prompt-level guarantee, not a structural one like --tools "".
• Codex exits 0 even when the turn fails. A bad model id, an expired login and a rate limit all produce a clean exit with a turn.failed event, so the adapter treats a missing turn.completed as a failure rather than trusting the exit code.
• No streaming. codex exec --json emits the answer in one item.completed, with no incremental text events, so this provider buffers instead of pretending to stream.

Not supported on either CLI: vision, embeddings (they stay on the local daemon), and the sampling knobs temperature / top_p / top_k / seed / stop / maxTokens: neither CLI exposes a flag for them, so they are dropped rather than silently approximated. Reconfiguring binPath or extraArgs means editing config.json; the model is changeable from the LLM tab.

Two things worth knowing before you switch a long-running agent onto either: each completion pays roughly 0.8 s of process startup, and subscription plans have session and weekly caps that an autonomous multi-step agent reaches much faster than interactive use. When a cap is hit, the CLI's own message is surfaced verbatim.

[!NOTE] Whether driving a subscription CLI from another agent is acceptable use is the vendor's call, not this project's. Atomic uses the officially documented headless mode and nothing else; the decision to use it is yours.

Some OpenAI-compatible backends (Tinker, certain vLLM/llama.cpp front-ends serving Qwen or Hermes-style models) emit tool calls as inline <tool_call>…</tool_call> text instead of the native tool_calls field. Atomic decodes these automatically on every OpenAI-compatible kind (openai-compatible, openrouter, aimlapi, gemini, qwen-openai-compatible); there is nothing to enable. Both block forms are accepted: Qwen's <function=…><parameter=…>…</parameter></function> and the Hermes JSON {"name": …, "arguments": {…}}.

A reply counts as tool calls only when the request offered tools, the response has no native tool_calls, and the whole trimmed content is <tool_call> blocks. Prose around a block keeps it a normal reply.

Qwen thinking models sometimes put the call in reasoning_content instead of content (#105). Reading that channel is the one Qwen-only part: set the provider kind to qwen-openai-compatible in config.json (with baseUrl + defaultChatModel) to enable it. Other kinds ignore calls quoted in the reasoning channel on purpose. There is no TUI wizard row for this kind yet; it is config-only for now.

{
  "llm": {
    "providers": [
      {
        "id": "tinker",
        "kind": "qwen-openai-compatible",
        "baseUrl": "https://your-tinker-host",
        "defaultChatModel": "Qwen3-32B"
      }
    ]
  }
}

Behavior:

• The tagged call is read from content. With qwen-openai-compatible it is also read from reasoning_content when content is empty or holds unparseable tag noise.
• Argument values are coerced against the offered tool's JSON schema; a call that does not match is dropped (fail-closed) rather than executed with guessed args.
• Streaming stays live: text/reasoning deltas stream as usual and the buffered final message is adapted once the stream closes.

Limitation for MCP tools: the schema coercion supports a fixed JSON-Schema subset and rejects unknown keywords such as $ref. Atomic's built-in tools are fine, but MCP tools that ship a draft-07 inputSchema with $ref (or other unsupported keywords) will fail coercion and remain prose. MCP tools called through tagged text are therefore unsupported for now.