Skip to content
Atomic Agent logo Atomic Agent docs

Troubleshooting

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

The agent won’t respond / no model

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

Terminal window
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:
Terminal window
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.

Port already in use / can’t reach the server

The managed llama-server defaults to http://localhost:8000. If another process holds that port, or you run the server elsewhere, point Atomic Agent at the right URL:

Terminal window
export ATOMIC_AGENT_LLAMA_URL="http://127.0.0.1:8080"

Or set localModels.url in config.json. In external mode, Atomic Agent only connects — it never spawns a server — so make sure your llama-server is actually up and reachable at that URL. It probes /health and /props at startup to detect the model profile.

The browser tools don’t work

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

Terminal window
# 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:

Terminal window
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.

Still stuck?