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.

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. Data only leaves your machine when a tool you can see makes it leave.

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, off by default
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 6000). 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)"]

    Browser --> Net((Internet))
    Http --> Net
    Skills --> Net
    Cloud --> Net
    Mcp --> Net
    Tg --> 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).

Lock the doors you don't need

Want a tighter sandbox? Run with approvals on (the default — agent.approvalRequired: true) 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.

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 and protected by a bearer token (--api-key or ATOMIC_AGENT_API_KEY).
• 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. Nothing phones home.
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 are macOS and Linux x64/arm64. Windows builds are not yet available.
• 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.