Isolation
Overview
Members who share the sample’s sandbox all run as its default user, usually root, so any member can read, change or delete another’s files and stop its processes (Sandboxes). Users isolation keeps them apart inside that one sandbox. Each member runs as its own Linux user, with a private home directory, and shares only the directories you list.
from inspect_ai.agent import react
from inspect_ai.tool import bash
from inspect_swarm import member, swarm, users
solver = swarm(
members=member(react, args={"tools": [bash()]}, name="w", count=3),
isolation=users(),
)isolation="users" is the same as users(). When the swarm starts, before any member does, it creates the users, their homes and the shared directories in the sandbox, then runs commands as the members to check that the boundaries hold. If any check fails, the swarm refuses to start.
Users isolation is a default boundary and a record of who made what, not containment. Members share one kernel and one sandbox root, and they can still reach each other in the ways listed under What is not isolated. When members must be truly apart, give each its own sandbox (Sandboxes).
What each member gets
A Linux user
swarm-<member>, such asswarm-w-1, that is not root. Every member is also in the groupinspect-swarm.A private home,
/scratch/<member>by default (users(home=...)). It is the member’s$HOMEand where its tools start. Only the member can read it, unlesspeers="read"opens every member’s home to the other members for reading (Permissions). The swarm creates it empty: it does not copy the image’s/etc/skel. It holds atmpdirectory, and a.profileand.bashrcthat set$TMPDIRto it.The shared directories,
/sharedread-write by default (Sharing).A paragraph at the end of its preamble that tells it its user and directories:
You run as the Linux user swarm-w-1, without root. Your private directory is /scratch/w-1 (your $HOME); other members cannot read it. Shared with all members: /shared (read and write). Use $TMPDIR for temporary files. Git refuses a repository another user created until you run
git config --global --add safe.directory <path>. Processes you leave running are stopped when you finish.
The member’s tools run as its user:
- The built-in tools that run commands in the sandbox, bash(), python(), bash_session(), text_editor(), grep(), list_files() and read_file(), run as the member and start in its home.
- A custom tool’s
sandbox().exec(), read_file() andwrite_file()calls that name no user run as the member too. Rawexec()calls keep the sandbox’s working directory unless they passcwd, so use absolute paths in raw file calls. - A call that names another user, such as
exec(..., user="root"), runs as that user. That is a grant made in code, and the record counts it (The record). - computer(),
web_browser()and skill() raise inside a member, and so do built-in tools built with anotheruser, such asbash(user="root"), and a bash_session() shared between members through an explicitinstance.
Members are not root. They cannot install system packages, write system directories or pip install without --user. Tasks that need root while the members work are unsuitable.
Bridged members
A bridged member’s CLI runs as the member too. inspect_swe 0.3.2 or later is needed, with claude_code() or codex_cli() run headless, as members run them:
from inspect_ai.agent import Agent, agent, react
from inspect_ai.tool import bash
from inspect_swe import claude_code
from inspect_swarm import (
member,
messages,
swarm,
swarm_bridged_tools,
swarm_tools,
users,
)
@agent
def worker() -> Agent:
return react(tools=[bash(), swarm_tools()])
@agent
def cc_worker() -> Agent:
return claude_code(bridged_tools=[swarm_bridged_tools(["messages"])])
solver = swarm(
members=[member(worker, count=2), member(cc_worker, name="cc", bridged=True)],
channels=[messages()],
isolation=users(),
)- The image needs
curlfor the bridged tools (Requirements and limits). - The CLI and every process it starts run as the member’s user. The CLI starts in the member’s home and keeps its settings there.
- inspect_swe installs the CLI from the host’s cache or a download, not from the image. Both agents refuse
version="sandbox"under users isolation, and the defaultversion="auto"installs the stable release. - The CLI’s model proxy, which the bridge runs in the sandbox, serves only the member’s user. A request to its port from another member, or from root, gets HTTP 403. If another member is already listening on the port the proxy needs, the bridge fails before the CLI starts, and the sample fails with the proxy’s error.
- When the member ends, its CLI and the processes the CLI left are stopped (Leftover processes).
centaurmode raises inside a member, and so do inspect_swe’s other agents and its ACP adapters.- Use one bridged agent type per swarm. inspect_swe gives each agent type its own port numbers, so the first Claude Code member and the first Codex member in one sandbox both need port 3001.
Leftover processes
When a member ends, however it ends, the swarm kills every process in the sandbox that still runs as the member’s user. It repeats the scan up to five times, since a process can start another between scans. This runs before the member’s end is recorded, so the member ends after its processes are gone. While it runs, operators cannot message or stop the member (Operators).
What the swarm found is the member’s reap in the result record. Stopping the processes never fails the member or the sample. When it cannot finish, the record says so instead.
The record
The result record (Scoring) gets these fields under users isolation. Without isolation they are null.
- Each member’s
user,uidandhome. - Each member’s
reap: itsstatus,killedandkilled_names(the processes the member left running after its tool calls returned, up to 50 names), andsurvivorsandsurvivor_names.statusisokwhen no process of the member’s user is left,survivorswhen some were still running after five rounds,timeoutwhen the swarm stopped waiting for the sandbox, anderrorwhen the sandbox could not run the command, with itsmessage. - Each member’s
foreign_execs: how many sandbox commands it ran as another user, such as a custom tool’sexec(..., user="root"). Inspect’s own sandbox operations are not counted. It counts named-user commands in every sandbox of the sample, and does not see calls a tool makes on the provider object (sandbox().as_type(...)) or file reads and writes. - The record’s
isolation_incomplete:truewhen some member that started may have left processes running, because itsreapdid not endokor did not run. The task’s scorer still runs. Analyses of what members left in the sandbox should exclude or report these samples.
The swarm’s metrics have the same check as reap_complete (Analysis).
Evidence
Users isolation adds two SwarmEvents to the swarm’s span, each with member null.
isolation, when the swarm starts, records the setup:
sandbox: the sandbox the members share.members: each member’sname,user,uidandhome.census_roots: the directories the census will scan, each with itspathandkind:sharefor arwshare,transientfor/tmp,/var/tmp,/dev/shmand/run/lock, andworld_writablefor the other directories on the root filesystem that every user can write.census_roots_capped:truewhen there were more than 200 such world-writable directories, and the census scans only the first 200.
census, once every member has ended and when the swarm ends without an error, records who owns the files under each census root. A file’s owner is the member that created it, even from a background process between tool calls. Its status is ok, or timeout or error with a message when the census failed; the swarm ends as usual either way. With ok, roots has one entry for each census root:
pathandkind, as above.status:ok,absentfor a root that is not a directory, orunreadablewith find’s firsterror, besides what it counted.members: for each member that owns entries there, itsentries, thebytesof its regular files, and up to 50paths, each with itstype(such asfile,directoryorsymlink) andpath. A path longer than 1,024 bytes is cut to that and markedtruncated.others: theentriesandbytesowned by anyone else.capped:truewhen the root had more than 10,000 entries, the most the census counts.paths_omitted: paths left out once the census had written 1 MiB of them. The counts include them.
Files under /tmp, /var/tmp, /dev/shm or /run/lock are outside the shares you gave. Their permissions can still keep other members from reading them. The census does not see reads, changes to existing files, files deleted before it ran, or traffic over sockets, so it is not a measure of how much members communicated.
Read the events from a sample in the log:
from inspect_ai.event import SwarmEvent
census = next(
e.data for e in sample.events if isinstance(e, SwarmEvent) and e.kind == "census"
)Requirements and limits
The sandbox must let commands run as root and as other users: Docker, or Kubernetes with a root container. The
localsandbox is refused.The image needs
useraddandgroupadd(packagepasswd),awkand GNUfind. With any share it also needssetfaclandgetfacl(packageacl), which the default Inspect image andpython:3.12-bookwormlack. Bridged members with bridged tools, such as swarm_bridged_tools(), also needcurl: inspect_swe runs it to check that those tools are ready before it starts the CLI. For a Debian image:FROM python:3.12-slim-bookworm RUN apt-get update \ && apt-get install -y --no-install-recommends acl curl \ && rm -rf /var/lib/apt/lists/*Homes and shares must sit under directories that are owned by root and not writable by group or others. A share must not be
/tmp,/var/tmp,/dev/shmor/run/lock, inside one or above one, and shares must not overlap each other or the homes’ parent directory. The homes must not exist yet, so leave them out of the image and the sample’sfiles.Setup refuses an ACL in a share or on the homes’ parent, and a mount inside a share or under the homes’ parent. In a
rwshare it refuses hard-linked files, devices, sockets, FIFOs and set-user-id or set-group-id files.Member names must be valid Linux user-name suffixes: lowercase letters, digits and
-, starting with a letter, at most 26 characters. Members cannot choose their own names (Members) or have their own sandboxes.One swarm with users isolation per sandbox in a sample. Another is refused, whether it runs after the first, beside it, in a subtask or in a fork.
users(sandbox=...)picks which of the sample’s sandboxes the members share.Bridged members need inspect_swe 0.3.2 or later, the first release that supports users isolation. Only
claude_code()andcodex_cli()are supported (Bridged members).The image and sandbox configuration are trusted, like task code that runs before the swarm. Setup refuses an existing
inspect-swarmgroup orswarm-<member>user or group, and checks thatsudo -n truefails for each member, but it does not audit the image for every setting that could give a member authority. See users() for the conditions setup does not check.Setup runs before the controller and counts towards the sample’s time. A time cap derived from the sample’s time limit is derived again after setup (Budgets).
Comparing arms
Members under users isolation are not root, and members in the shared default usually are. Comparing isolation=None with users() therefore changes privilege as well as isolation. To measure isolation alone, run the other arms at the same privilege: a swarm of one member under users() for the single-agent arm, and users(peers="read") with the working area as a rw share for an arm where members can read each other’s work. Members can still make their own files private (Permissions).