Why local-first

Atomic Agent runs on your computer. The language model, your conversations, your memory, your tasks — all of it lives in a folder on your machine, not on someone else’s server.

That one design choice changes what the agent can promise you. Nobody bills you per token. No conversation leaves your machine unless you point it at the internet. And because every part is on disk, you can open it up, read it, and change it.

The one thing that does leave by default is a small stream of anonymous usage stats — model name, timing, token counts, never your content. One line in config.json turns it off. See Telemetry below.

Developer Preview

Atomic Agent is a Developer Preview. Commands, config keys, and behavior are still moving. Pin a release if you need a stable integration.

What “local-first” means here

By default, the agent talks to a local llama-server (llama.cpp) running on 127.0.0.1. It does inference on your own GPU or CPU using a quantized model you downloaded once. Your prompts, the model’s replies, and everything the agent remembers stay on your disk.

Own the control plane

The runtime, the model, the tool loop, and the data are all processes and files you control. No remote orchestrator decides what runs.

Private by default

Inference is local. Memory is a local SQLite file. Your prompts, replies and files leave only when a tool you can see makes them leave. Anonymous usage stats are the one exception, and they are one flag away from off.

No per-token fees

You pay for electricity, not for tokens. Run the agent for hours; the marginal cost is your own hardware.

Hackable all the way down

Config is a JSON file. Skills are folders. Traces are NDJSON. Open any of it in your editor.

Where your data actually lives

Everything the agent persists goes under one state directory — by default ~/.atomic-agent, overridable with ATOMIC_AGENT_STATE_DIR.

What	Where	Notes
User config	<stateDir>/config.json	Plain JSON, versioned, edit by hand or via atomic-agent config set
Secrets	<stateDir>/.env	API keys, TELEGRAM_BOT_TOKEN; written with mode 0600
Memory	memory.sqlite	Profile facts, notes, lessons, procedures (FTS5 + optional embeddings)
Sessions	sessions.sqlite	Full conversation transcripts
Tasks	tasks.sqlite	Scheduled and recurring task queue
Traces	<traceDir>/<sessionId>.ndjson	Append-only, on by default for run, tui and serve
Models	<dataDir>/models/, <dataDir>/backend/	GGUF weights + the llama-server binary

# Point the whole runtime at a different state directory
ATOMIC_AGENT_STATE_DIR=/Volumes/encrypted/atomic atomic-agent tui

Local does not mean redacted

Your state directory is sensitive. Secrets in .env and any API keys in config.json are stored in plaintext (the .env file is chmod’d to 0600, but config.json is not encrypted). Treat the folder like you would an SSH key directory. Traces, when enabled, capture prompts and user messages verbatim with no secret redaction.

No per-token fees

Because the default backend is a local llama-server, there is no metered API in the loop. The runtime is built to make that local model affordable to run for long, multi-step sessions:

• Stable prompt prefix + KV-cache reuse. The persona, tool catalog, and skill index form a byte-stable prefix that llama-server caches once per session. Each step reuses it via cache_prompt and slot affinity instead of reprocessing it.
• Bounded prompts. Every step is budgeted (agent.tokenBudget, default 3000). Memory grows in SQLite, not in the prompt — the model only sees compact pointers.
• Compressed tool results. Verbose output is summarized before it re-enters the conversation, so a noisy grep or test run doesn’t blow the budget.

If you want a cloud model for some work, you can configure one under llm.providers[]. That is an explicit opt-in, and it is the point where tokens start costing money and data starts leaving your machine — see Egress below.

# Run fully local, managed model lifecycle
atomic-agent models pull qwen-3.5-4b
atomic-agent models use qwen-3.5-4b
atomic-agent tui

Egress: the points where data can leave

Local-first does not mean airtight. The agent is useful precisely because it can act in the world — browse, fetch, run shell commands. The honest framing is: egress is explicit and enumerable. Here is every door out.

flowchart LR
    Core["atomic-agent runtime<br/>(local model, memory,<br/>sessions, tasks)"]
    Core --> Browser["browser.* tools<br/>(navigate, fetch)"]
    Core --> Http["os.http / os.web.fetch<br/>os.web.search"]
    Core --> Shell["os.shell<br/>(inherits your env)"]
    Core --> Skills["skill.run_script"]
    Core --> Cloud["cloud LLM providers<br/>(llm.providers, opt-in)"]
    Core --> Mcp["MCP servers<br/>(mcp.servers, opt-in)"]
    Core --> Tg["Telegram channel<br/>(opt-in, single-user)"]
    Core --> Tel["telemetry<br/>(on by default)"]
    Core --> Upd["update check<br/>(on by default)"]
    Core --> Hub["ClawHub skill registry<br/>(on by default)"]

    Browser --> Net((Internet))
    Http --> Net
    Skills --> Net
    Cloud --> Net
    Mcp --> Net
    Tg --> Net
    Tel --> Net
    Upd --> Net
    Hub --> Net

    style Core fill:#e8f5e9
    style Net fill:#fff3e0

Each door is gated:

• Browser and HTTP tools (browser.navigate, os.web.fetch, os.web.search, os.http) reach the internet on purpose. Non-safe HTTP requests and non-http(s) browser navigation are dangerous operations and pass through the approval gate.
• Shell and skill scripts (os.shell, skill.run_script) run with the agent process’s environment and can do anything you can do at a terminal. Both are approval-gated. Shell commands additionally pass a command guard (hardline blocks for rm/mkfs, dangerous-pattern checks).
• Cloud LLM providers are off unless you configure llm.providers[]. When active, prompts go to that provider.
• MCP servers are off unless listed in mcp.servers[]. Each server has a trust level; the default is approval_gated (fail-closed), so even hallucinated tool names from a stale server land in the safe lane.
• Telegram is constructed but inert unless telegram.enabled is true and a token is present. It is deliberately single-user (owner-pairing, fail-closed when ownerUserId is null).

The last three doors are the ones that are open on a fresh install. None of them carries your content:

• Telemetry sends anonymous usage stats. Off with analytics.enabled: false — see Telemetry.
• Update check asks the GitHub releases API whether a newer version exists when the TUI starts. Off with ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP=false.
• ClawHub is the skill registry behind skill browse and skill search. It is contacted only when you run those commands or open the Skills panel. Off with skills.clawhub.enabled: false.

Lock the doors you don't need

Want a tighter sandbox? Keep approvals strict (the default — agent.approvalLevel: 1) so every dangerous tool waits for your y/n. Leave mcp.servers[] empty and telegram.enabled false. Skip configuring any llm.providers[] and the agent never reaches a cloud model. Set analytics.enabled: false, skills.clawhub.enabled: false and ATOMIC_AGENT_UPDATE_CHECK_ON_STARTUP=false and the agent makes no network request you did not ask for.

Telemetry

Atomic Agent sends anonymous usage stats so we can see which models people run, where the agent is slow, and what crashes. It is on by default and takes one line to turn off.

What is sent: an anonymous install id, platform, app version, and per message the model and provider name, response latency, step count, token counts and estimated cost.

What is never sent: your prompts, the model’s replies, file contents, file paths, tool arguments, memory, or your IP address. The scrubber that guards this is an allowlist — fields must be explicitly permitted to travel, so nothing leaks by omission.

// config.json — disables usage stats and crash reporting together
{
  "analytics": {
    "enabled": false
  }
}

That single flag governs both the usage stats and the crash reporter. There is no separate switch to remember.

You can also flip it without leaving the TUI. /analytics on, /analytics off, and /analytics status toggle the same setting and report its current state; /privacy analytics on|off is the same command under the Privacy panel’s namespace. Either form opens the Privacy tab, where a toggles it directly.

Own the control plane

“Control plane” means the part that decides what runs and when. With a hosted agent, that lives on a vendor’s servers. With Atomic Agent, it is createAgentRuntime running in your process, wiring together the model provider, tool registry, memory stores, and the agent loop. You start it, you stop it, you see everything it does.

Concretely, you own:

• The entry point. CLI (atomic-agent run), TUI (atomic-agent tui), HTTP server (atomic-agent serve), or the Tauri sidecar — all construct the same local runtime.
• The serving surface. atomic-agent serve exposes an OpenAI-compatible API on a host and port you choose, bound to 127.0.0.1 by default. Pass --api-key (or set ATOMIC_AGENT_API_KEY) to require a bearer token. Without one the server starts unauthenticated and says so in its startup line: auth=none. Always set a key before changing --host off localhost.
• Concurrency and ordering. A per-session FIFO turn controller serializes turns; different sessions run in parallel. This is enforced locally, not by a remote queue.

# Your machine becomes the API. Your prompts and files never leave it.
atomic-agent serve --host 127.0.0.1 --port 8787 --api-key "$MY_KEY"

Hackable all the way down

Local-first only matters if you can actually reach in and change things. Every layer is a file or a documented surface:

• Config is config.json — read it, edit it, or drive it with atomic-agent config get / atomic-agent config set '<json>'.
• Skills are folders (SKILL.md + optional scripts/). Install with atomic-agent skill install <path>, list with atomic-agent skill list, toggle with atomic-agent skill enable|disable.
• Memory is a SQLite database you can open with any SQLite client, or browse read-only in the TUI Memory tab.
• Traces are append-only NDJSON. Turn them on (tracing.trace.enabled), then inspect with atomic-agent trace list / trace show <sessionId> or detect prompt drift with atomic-agent trace replay <sessionId>.
• Models are managed by you: atomic-agent models list|pull|use|start|stop|status.

Note

The bundled CLI ships as a single self-contained binary, but the model backend (llama-server) and browser (Chrome/Edge/Chromium) are not bundled — they’re external dependencies you install and control. That separation is intentional: the pieces that touch the network are ones you can swap, inspect, and pin yourself.

When you might not want local-first

Being honest about the tradeoffs:

• Hardware matters. Local inference quality depends on the model your machine can run. A 4B quantized model is not a frontier cloud model. You can mix in a cloud provider for hard turns, at the cost of egress and per-token fees.
• Platform support. Releases today cover macOS, Linux x64/arm64, and Windows.
• You operate it. No vendor patches your runtime overnight. Updates are explicit (atomic-agent self-update or your package manager).

For most local automation — browsing, files, shell, document extraction, memory that persists across sessions — keeping everything on your machine is the whole point.

Related

Configuration & Secrets

Full config.json schema, .env handling, and every ATOMIC_AGENT_* env var.

Approval gates

How dangerous tools pause for your decision, and how --no-approval changes the contract.

Memory system

Profile facts, notes, lessons, and procedures — how memory grows on disk without bloating the prompt.

Local models

Managing llama-server, GPU/VRAM budgeting, and the embedding daemon.