Workflow concurrency derives from CPU count, throttling I/O-bound fan-out to 2 agents in a cloud container (2 vCPUs observed vs 4 documented)
Related to #63938, from the opposite end of the hardware range. That report is a 10-core Mac capped at 8; this is a cloud container capped at 2. Filing separately because two observations here are distinct from that feature request: the cap is derived from the wrong resource for a whole workload class, and the container reports half the documented vCPU allocation.
Environment
- Claude Code 2.1.42, entrypoint
remote_cowork(Cowork session in an Anthropic-hosted cloud container;CLAUDE_CODE_REMOTE_ENVIRONMENT_TYPE=cloud_default) nproc-> 2;free -m-> 8023 MB- Environment runner self-identifies as
staging-96f68f2a49 - Observed concurrent
agent()calls: 2
What I ran
A 20-agent read-only research workflow. Each agent performs 8-15 WebSearch/WebFetch calls and returns a structured JSON dossier. Purely network-bound - no compilation, no test runs, negligible disk I/O.
Measured behavior
The queue is in exact lockstep with 2 slots. Each agent's start time against the previous agent's completion:
| agent starts (UTC) | previous agent finished | delta |
|---|---|---|
| 22:38:31.775 | 22:38:31.641 | 134 ms |
| 22:39:04.196 | 22:39:04.061 | 135 ms |
| 22:42:26.113 | 22:42:25.993 | 120 ms |
| 22:45:26.313 | 22:45:26.205 | 108 ms |
| 22:50:04.557 | 22:50:04.377 | 180 ms |
The core issue
While this ran, /proc/loadavg read 0.08. Both CPUs sat essentially idle for the entire run - every agent was blocked on HTTP, not on compute. The documented constraint is:
Up to 16 concurrent agents, fewer when Claude Code has fewer CPUs available, including inside a CPU-limited container | Bounds local resource use
That safeguard is sound for the workload Claude Code was designed around: agents that compile, run tests, and touch disk. It transfers poorly to research and review sweeps - which are precisely the use cases the same page highlights ("Research a topic across many sources", "Audit many files for the same issue"). Here it turned roughly 7 minutes of wall-clock into roughly 50, with no corresponding protection of machine stability.
A suggestion narrower than a raw override
Rather than only exposing maxConcurrentAgents, consider letting the script declare the workload class - parallel(tasks, { bound: 'io' }) - or deriving the ceiling from observed load rather than core count. A bare maxConcurrency knob asks the script author to know the host's core count, which in a cloud session the author generally does not.
A related inconsistency
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (default 20, added in 2.1.217) makes the Agent tool's concurrency configurable, and the sub-agents page explicitly notes that "Workflow agents and agent team teammates follow their own limits". So the same session, on the same hardware, for the same work, can run 20 concurrent Agent-tool subagents but only 2 concurrent workflow agents. The practical effect today is that authors are pushed away from the Workflow tool toward hand-rolled parallel Agent calls purely to escape the cap - the opposite of what the tool exists for.
Possibly a separate infrastructure issue
The cloud environments page states that Anthropic-hosted cloud sessions run with "approximate resource ceilings that may change over time: 4 vCPUs, 16 GB of RAM, 30 GB of disk", and that the same environments apply to sessions started from the Desktop app. This container reports 2 vCPUs and 8 GB - half of both. I can't determine whether Cowork sandboxes are allocated differently, whether the cgroup exposes half the VM, or whether this is specific to the staging-* runner this session landed on. Flagging it because it directly halves the workflow cap through the formula above: at the documented 4 vCPUs the cap would be twice as high. Happy to supply the container ID privately if that helps triage.