Skip to main content
Agents that run in parallel on one machine can use all of its CPU and memory, which slows down Xum and everything else on the machine. A resource limit caps what all local agent commands use together. Xum enforces it with a Linux cgroup v2, so it works only on Linux.

​
Set the limits

In Settings → Agents → Resource limits, turn on the switch. Then enter a CPU limit in cores (fractions such as 2.5 work) and a Memory limit in GiB. An empty field means no limit. The value saves when you leave the field. The line under the fields shows the result:
  • Active: agent commands share the limits. The line names the cgroup they run in.
  • Not applied: the line gives the reason. Fix the cause (see Status messages), then click Try again.
A changed limit applies at once to agent commands that already run under the limit. Commands that started while no limit applied keep running without one. To stop the limits for a while, turn off the switch. The limits stop at once, also for agent commands that already run under them. Xum keeps the values, and they apply again when you turn the switch back on.

​
What the limit covers

The limit covers the commands of local and worktree workspaces: bash tool commands in the foreground and background, tool hooks, init and lifecycle hooks, MCP servers that run as local commands, and the other commands Xum runs in the workspace for the agent. It does not cover:
  • Terminals that you open.
  • The desktop that desktop tools start, and the programs that the desktop starts.
  • Xum itself, including the git commands it runs to create and remove worktrees, and repository hooks such as post-checkout that those commands run.
  • Docker, dev container, SSH, and Coder workspaces. Their commands run in the container or on the remote machine.
While the switch is on, xum run and xum workflow apply the saved limits to their commands too. Their commands share one limit with the agents of a running Xum only when both use the same base cgroup (see How Xum sets up the cgroup), for example when you start them from a shell in xum-app. Things to know about the limits:
  • The CPU limit is a quota: with 2.5, agent commands together get 250 ms of CPU time in each 100 ms period, on any number of CPUs. Programs built with Go 1.25 or later set their default GOMAXPROCS from it, unless their go.mod names an earlier Go version.
  • The memory limit covers RAM, not swap. If the machine has swap, agent commands can still use it.
  • If you lower the memory limit below what agent commands use now, the kernel reclaims memory and can stop agent processes with the out-of-memory killer.

​
How Xum sets up the cgroup

A user can move a process into a cgroup only inside a cgroup tree that is delegated to that user. Xum therefore uses the cgroup it runs in, which this page calls the base cgroup. When you set a limit, Xum:
  1. Enables the cpu and memory controllers for the base cgroup’s children. A cgroup that does this cannot hold processes itself, so Xum first moves the processes of the base cgroup into a child named xum-app.
  2. Creates the child xum-agents and writes the limits to its cpu.max and memory.max.
  3. Moves each new agent command into xum-agents before the command runs.
When you clear the limits or turn off the switch, Xum writes max to both files. It does not move processes back or delete the cgroups. After the first setup, start other processes in xum-app, not in the base cgroup. A Xum that you restart from a shell in xum-app uses the same base cgroup again.

​
Start Xum in a delegated cgroup

If the status says that Xum cannot manage its cgroup, start Xum in a cgroup that your user owns.

​
With systemd

Start Xum in a scope with delegation:
If the status then says that the cpu controller is not available, the systemd user manager does not have it. To delegate it, create /etc/systemd/system/user@.service.d/delegate.conf with:
Then run sudo systemctl daemon-reload and log in again.

​
With sudo (containers and Coder workspaces)

Without a systemd user manager, create the cgroup as root, give it to the user that runs Xum, and start Xum from a shell that root moved into it. Replace coder with that user:
Root must move the shell: a user can move a process only when it may write cgroup.procs of the closest cgroup that contains both the old and the new cgroup, and here that is the root cgroup. /sys/fs/cgroup/xum/cgroup.controllers must list cpu and memory. If it does not, enable them in the parent’s cgroup.subtree_control as root. In a Coder workspace, put these steps in the startup script before Xum starts. The user controls only this cgroup and its children. Limits on its parents still apply.

​
Status messages

If a command prints xum: could not apply the agent resource limit to this command, the command ran without the limit, for example because the xum-agents cgroup was removed. Click Try again in Settings, or restart Xum.