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 SeaShell in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install SeaShellRelated guides
Atlas with Command R 35B (Ollama) in 2026
Explore Atlas with Command R 35B (Ollama) in 2026. This free, self-hosted model offers a 128K context window, excelling at RAG and tool use for your terminal-native AI coding agent.
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 in 2026
Drive Atlas with GPT-5.1 Codex in 2026. This OpenAI model offers 400K context for long-horizon coding at $1.25/Mtok input, $10/Mtok output, balancing cost and capability.
Atlas vs Codebuff: Terminal AI Coding Agents in 2026
Comparing Atlas and Codebuff in 2026 for terminal AI coding agents. Atlas offers a free core with permission-gated tools and diff review. Codebuff provides free hours on DeepSeek V4 Flash.
Atlas with GPT-5.4 mini for Developers in 2026
Discover how Atlas leverages GPT-5.4 mini in 2026. This fast, mid-tier model offers a 400K token context window and competitive pricing for subagent tasks within Atlas.
Atlas with Phi-4 Mini 3.8B (Ollama) in 2026
Discover how Atlas leverages Phi-4 Mini 3.8B (Ollama) for efficient, local AI coding in 2026. This 2.5GB model offers native function calling and a 128K context window, ideal for tool routing and summaries.
Atlas with GPT-5.1 in 2026
Explore GPT-5.1's 400K context and $1.25/Mtok input pricing with Atlas in 2026. A powerful reasoning model, it integrates deeply with Atlas's agent workflow for developers.
Atlas with GPT-5.2 in 2026
Explore Atlas with GPT-5.2, OpenAI's December 2025 refresh. Discover its 400K token context, $1.75 input cost, and how it powers terminal-native AI coding in 2026.