Atlas fails with Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true because the task tool gates background execution behind an experimental runtime flag and fails the call rather than silently downgrading to a foreground run. The fix is to export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas, if you accept the experimental behavior, and restart Atlas, since runtime flags are read at startup. Otherwise, run the subagent in the foreground by omitting the background option.
Why does Atlas require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
Atlas requires ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true because the task tool gates background execution behind an experimental runtime flag. In the 2026 build the tool fails the call rather than silently downgrading to a foreground run, so you always know which execution mode you got.
The hard failure is a deliberate design choice. A silent downgrade would leave you believing a long job was running detached in the background while it was actually blocking your session, or finishing and reporting in a way you did not plan for. By refusing the call outright, Atlas keeps the contract explicit: you asked for a background subagent, and background subagents are experimental, so either you opt in with the flag or you pick a different execution mode. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, and the flag governs only the background half of that capability.
How to enable background subagents in Atlas
Enable background subagents in Atlas in 2 steps. First, export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas, if you accept the experimental behavior. Second, restart Atlas, because runtime flags are read at startup and a variable set after launch has no effect on the running process.
Set the variable in the same shell that starts Atlas, not in a different terminal or a shell that never spawns the process. If you launch Atlas from a desktop shortcut, a tmux pane, or an editor integration, the environment that matters is the one that actually spawns the binary, and exporting the flag in an unrelated login shell will not reach it. Persist the export in your shell profile if you want the behavior across sessions. Say the caveat out loud: the name contains EXPERIMENTAL for a reason, so opt in knowing the behavior may change.
How to run an Atlas subagent in the foreground instead
Run the Atlas subagent in the foreground by omitting the background option. Foreground subagents are not gated behind ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true, so the task launches immediately with 0 environment changes and 0 restarts, which makes it the shortest path when you simply need the work done.
Foreground is the right default for most work. The subagent runs, returns its result into the parent session, and the transcript stays coherent. Reach for foreground whenever the task is something whose answer you need before the next step, which is the majority of agent work: an exploration pass, a targeted search, or a scoped edit. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and that gating applies to the subagent's tool calls whether it runs in the foreground or in the background, so choosing foreground costs you nothing in safety.
How to get concurrency in Atlas without background subagents
Prefer several foreground Atlas task calls in parallel over 1 background job when concurrency is all you need. Parallel foreground tasks require no runtime flag, no restart, and no opt-in to ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true, and Atlas still fans the work out across multiple subagents.
Concurrency and detachment are different needs, and the flag only governs detachment. If your goal is to search three parts of a repository at once, or to have several subagents investigate independent questions, issue multiple task calls and let them run together in the foreground. You get the parallelism without touching an experimental code path. Background execution earns its keep in a narrower case: a long-running job you genuinely want to detach from the conversation and collect later. If that is not what you are doing, foreground parallelism is the simpler answer.
How to verify background subagents are enabled in Atlas
Verify the Atlas fix in 2 moves: restart Atlas, then re-launch the background task. A task that starts without printing Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true confirms the flag was read at startup and the experimental background path is now active.
If the same error appears after you exported the variable, the running Atlas process did not see it. The two usual reasons are that Atlas was never restarted, since runtime flags are read at startup, or that the export happened in a shell other than the one that launches Atlas. Check the environment of the process itself rather than the shell you happen to be typing in. Once the flag is genuinely in the launching environment and Atlas has been restarted, the background task starts and the parent session continues while the subagent works.
How to fix it
- 01Export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas, if you accept the experimental behavior.
- 02Restart Atlas after setting the variable; runtime flags are read at startup.
- 03Otherwise run the subagent in the foreground by omitting the background option.
- 04Prefer several foreground task calls in parallel over one background job if you only need concurrency.
Frequently asked questions
- how to fix Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
- Export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas and restart Atlas, since runtime flags are read at startup. Otherwise, run the subagent in the foreground by omitting the background option.
- why does Atlas fail instead of running the subagent in the foreground automatically
- The Atlas task tool gates background execution behind an experimental runtime flag and fails the call rather than silently downgrading to a foreground run, so the execution mode you asked for is never quietly changed.
- do I need to restart Atlas after setting ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS
- Yes. Restart Atlas after setting the variable, because runtime flags are read at startup and an already-running process will not pick up the new value.
- are background subagents in Atlas stable
- No. Background subagents are gated behind an experimental runtime flag, ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true. Enable them only if you accept the experimental behavior.
- how do I run Atlas subagents in parallel without the experimental flag
- Prefer several foreground task calls in parallel over one background job if you only need concurrency. Foreground subagents are not gated behind the experimental flag.
- where should I export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS
- In the shell that launches Atlas. A variable exported in an unrelated terminal never reaches the Atlas process, and the flag is read at startup.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Command R 35B (Ollama): A RAG-Native Model for Retrieval-Heavy Work in 2026
Run Atlas on Command R 35B (Ollama): Cohere's 19GB RAG and tool-use model with a 128K context, free self-hosted. Check the research license before commercial use.
Atlas for Bun: Terminal-Native AI Coding in 2026
Atlas is a terminal-native AI coding agent for Bun. Swap Node compatibility shims for Bun.serve and bun:sqlite, iterate with bun test, and format with bun fmt in 2026.
Atlas with GPT-5.1 Codex: Plan First, Then Build in 2026
GPT-5.1 Codex in Atlas: a frontier model from OpenAI at $1.25 per Mtok input, $10 per Mtok output, built to execute an approved plan across a long tool chain.
Atlas vs Codebuff: Terminal AI Coding Agents in 2026
Atlas and Codebuff are terminal AI coding agents for 2026. Compare Atlas's terminal-native TUI, permission-gated tools, and diff review with Codebuff's multi-agent system and flexible pricing.
Atlas with GPT-5.4 mini: A Reasoning Mini Tier for 2026
GPT-5.4 mini runs $0.75 / $4.50 per Mtok on a 400K window, undercutting Claude Haiku 4.5's $1 with double the context. A reasoning-capable small_model for Atlas.
Atlas with Phi-4 Mini 3.8B (Ollama): Native Function Calling at 2.5GB in 2026
Phi-4 Mini 3.8B (Ollama) is a 2.5GB model with 128K tokens (131,072) of context and native function calling, Free (self-hosted). The Atlas small_model that can route tools.
Atlas with GPT-5.1: The Cheapest Full Size GPT-5 Input Price in 2026
GPT-5.1 in Atlas: 400K context, $1.25 per Mtok input and $10 per Mtok output, cheaper on input than every GPT-5 release that followed it in 2026.
Atlas with GPT-5.2: The 400K General Purpose GPT in 2026
GPT-5.2 runs Atlas on a 400K context with 128K max output at $1.75 per Mtok input, $14 per Mtok output. Setup, the price rise from GPT-5.1, and the Codex tradeoff.