Troubleshooting

Most problems fall into one of four buckets: the model server, GPU selection, ports, or the browser. Start with whichever matches your symptom.

Check your Node version first

Atomic Agent requires Node.js 25.7.0 or newer. An older runtime can fail in confusing ways well before any of the causes below apply, so run node --version before you debug anything else.

The agent won’t respond / no model

Atomic Agent can’t do anything without a healthy model server behind it. Check the daemon first:

atomic-agent models status

This polls the server’s /health endpoint. If it doesn’t report ok:

• Nothing is running. Start the managed daemon: atomic-agent models start.
• No model selected. Pull and select one: atomic-agent models pull qwen-3.5-4b then atomic-agent models use qwen-3.5-4b.
• The daemon timed out. Managed mode waits up to 30s for /health to return ok. A large model on a slow disk can exceed that on first load — run models start again; the model is cached after the first pull.

”Insufficient VRAM” or the model won’t load

Atomic Agent computes a VRAM budget before loading a model. On macOS it uses 75% of unified memory; on Linux and Windows it reads the selected GPU’s reported VRAM.

• Pick a smaller model. The default qwen-3.5-4b is the lightest starting point. Run atomic-agent models list for the catalog.
• Confirm the right GPU was picked. Enumerate devices and select one explicitly:

atomic-agent models devices                # list detected GPUs
atomic-agent models use-device auto        # or: cpu | Vulkan0 | Vulkan1 …

auto prefers a discrete GPU over an integrated one, even if the integrated GPU reports more memory. Force cpu if you want to run without the GPU entirely.

Note

GPU acceleration in managed mode uses Vulkan, which covers NVIDIA, AMD, and Intel through one path. Device enumeration runs llama-server --list-devices, with an nvidia-smi fallback for the pre-download VRAM check.

Port already in use / can’t reach the server

Which knob you reach for depends on the mode you run in.

Managed mode — Atomic Agent spawns llama-server itself on port 19091. If another process already holds that port, move it in config.json:

{ "localModels": { "managed": { "port": 19091 } } }

External mode (the default) — Atomic Agent only connects; it never spawns a server. The default URL is http://127.0.0.1:8080. Point it wherever your server actually listens:

{ "localModels": { "url": "http://127.0.0.1:8080" } }

Make sure that server is genuinely up and reachable at that URL — the agent probes /health and /props at startup to detect the model profile, and reports llm_unavailable when neither answers.

The browser tools don’t work

Browser binaries aren’t bundled — install Chrome, Edge, or Chromium yourself first. Then, if launching fails:

# Point at the right channel or an explicit binary
export ATOMIC_AGENT_BROWSER_CHANNEL=chrome            # chrome | msedge | chromium
export ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium

# Attach to a browser you already run, instead of launching one
export ATOMIC_AGENT_BROWSER_CDP_URL=http://127.0.0.1:9222

Inside a container or CI, the browser sandbox can fail to start. Disable it only in those environments:

export ATOMIC_AGENT_BROWSER_NO_SANDBOX=1               # containers / CI only

Missing tools on Linux

Some desktop tools (clipboard, notifications, window control) depend on small system packages that aren’t bundled — for example xclip, libnotify/notify-send, and wmctrl. Atomic Agent probes for them at startup and reports what’s available in its capabilities summary, so if a tool is missing it simply won’t reach for it. Install the ones you need — see the Installation → Linux notes.

A config change didn’t take effect

Config is cached at runtime. Secrets written to .env (like a Telegram token) and some config edits are picked up after a restart, not mid-session. Restart the agent, or reset the cache, if a change doesn’t seem to apply.

Reporting a bug

/dump in the TUI packages the state we need to diagnose a problem. It writes a timestamped zip under ~/Documents/atomic-agent-debug/ containing three things: a manifest.json describing what was collected, a tui-snapshot.json captured at the exact moment you pressed it, and the NDJSON trace files for your most recent sessions. Sessions whose traces are missing are listed in the manifest as skipped rather than failing the export.

Attach the zip to a GitHub issue and it usually saves a round of questions.

The zip contains your conversations

The snapshot includes the chat messages, feed, logs, and reasoning entries from the session, and the traces are the full step-by-step record of recent runs — prompts, tool calls, and file paths included. Open the zip and read it before you attach it to a public issue, and strip anything you would not post yourself.

Still stuck?

• Re-read the relevant page: Installation, Local models, or Configuration.
• Check the FAQ.
• Open an issue on GitHub with your OS, the output of atomic-agent models status, and atomic-agent models devices.