> ## Documentation Index
> Fetch the complete documentation index at: https://xum.cdr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Resource Limits

> Set one CPU and memory limit that all local agent commands share

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](#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](#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:

```bash theme={null}
systemd-run --user --scope -p Delegate=yes xum server
```

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:

```ini theme={null}
[Service]
Delegate=cpu memory pids
```

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:

```bash theme={null}
sudo mkdir /sys/fs/cgroup/xum
sudo chown coder /sys/fs/cgroup/xum /sys/fs/cgroup/xum/cgroup.procs \
  /sys/fs/cgroup/xum/cgroup.subtree_control /sys/fs/cgroup/xum/cgroup.threads
echo $$ | sudo tee /sys/fs/cgroup/xum/cgroup.procs
xum server
```

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

| Message | What to do |
| - | - |
| Agent resource limits need Linux with cgroup v2. | Limits are not available on macOS, Windows, or Linux with cgroup v1. |
| xum runs in cgroup …, which the user running xum cannot manage | [Start Xum in a delegated cgroup](#start-xum-in-a-delegated-cgroup). |
| The cpu (or memory) controller is not available in cgroup … | Enable the controller in the parent's `cgroup.subtree_control`, or delegate it with systemd. |
| xum runs in the root cgroup. | Start Xum in a cgroup of its own. Xum does not move every process of the machine. |
| … the agent cgroup of another xum … | This Xum runs inside an agent command of another Xum, whose limits already apply to it. |
| A test command ran in cgroup … | Another program moved Xum's test command to a different cgroup. Stop that program from moving Xum's processes. |
| Could not remove the limits from the agent cgroup: … | Agent commands that still run in `xum-agents` keep the old limits. Fix the cause, then click **Try again**. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.