Skip to main content

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 as swarm-w-1, that is not root. Every member is also in the group inspect-swarm.

  • A private home, /scratch/<member> by default (users(home=...)). It is the member’s $HOME and where its tools start. Only the member can read it, unless peers="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 a tmp directory, and a .profile and .bashrc that set $TMPDIR to it.

  • The shared directories, /shared read-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() and write_file() calls that name no user run as the member too. Raw exec() calls keep the sandbox’s working directory unless they pass cwd, 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 another user, such as bash(user="root"), and a bash_session() shared between members through an explicit instance.

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.

Sharing

users(shared=...) lists the directories every member shares, each read-write ("rw") or read-only ("ro"). The default is one read-write share, /shared. Directories that do not exist are created.

from inspect_swarm import Share, users

isolation = users(
    shared=[
        Share(path="/shared", access="rw"),
        Share(path="/data", access="ro"),
    ],
    peers="read",
)

A share can also be given as a mapping, as in {"path": "/data", "access": "ro"}.

  • In a rw share, members can read, create, change, rename and delete each other’s files. Files already there, such as the sample’s files, are kept. Setup makes them readable and writable by every member, and sets a default ACL so that new files are too, whatever a member’s umask. See Permissions for what a member can still make private.
  • A ro share is used as it is: setup does not change it. Every member must already be able to read every entry in it and search every directory, and none may be able to write it. Set its modes in the image.
  • When the image has git, setup marks each rw share, and each repository near its top, as a safe directory, and makes those repositories group-shared. A repository a member creates later belongs to that member, so other members’ git refuses it until they run git config --global --add safe.directory <path>, as their preamble says.

The default filesystem channel tells members to share files in /shared, append to /shared/notes.md and keep their own work in /scratch/<member>, which match the defaults of users(). If you change one, change the other. The swarm refuses a filesystem channel whose scratch is not the members’ home, whose shared directory is not a rw share, or whose notes file is in none.

Permissions

Setup sets the permissions once, when the swarm starts. It does not enforce them afterwards. The default ACL in a rw share overrides a restrictive umask, but not a mode given when a file is created, or a later chmod. A member can still make a file or directory in a share, or in its home under peers="read", that the other members cannot read. For example, mktemp -d creates a directory only its owner can use. In a share, run chmod g+rwx <directory> on it if the other members need it.

What is not isolated

A member can still:

  • See the other members’ processes and their command lines.
  • Share files through /tmp, /var/tmp, /dev/shm and /run/lock, which every user can write. The census records who left files there (Evidence).
  • Connect to the other members’ sockets on localhost.
  • Use the CPU, memory and process table that every member shares. A member that uses up memory can get a peer’s process killed. Size the sandbox for every member at once (Sandboxes).

Anything that gets a member root gets it everything.

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 curl for 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 default version="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).
  • centaur mode 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, uid and home.
  • Each member’s reap: its status, killed and killed_names (the processes the member left running after its tool calls returned, up to 50 names), and survivors and survivor_names. status is ok when no process of the member’s user is left, survivors when some were still running after five rounds, timeout when the swarm stopped waiting for the sandbox, and error when the sandbox could not run the command, with its message.
  • Each member’s foreign_execs: how many sandbox commands it ran as another user, such as a custom tool’s exec(..., 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: true when some member that started may have left processes running, because its reap did not end ok or 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’s name, user, uid and home.
  • census_roots: the directories the census will scan, each with its path and kind: share for a rw share, transient for /tmp, /var/tmp, /dev/shm and /run/lock, and world_writable for the other directories on the root filesystem that every user can write.
  • census_roots_capped: true when 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:

  • path and kind, as above.
  • status: ok, absent for a root that is not a directory, or unreadable with find’s first error, besides what it counted.
  • members: for each member that owns entries there, its entries, the bytes of its regular files, and up to 50 paths, each with its type (such as file, directory or symlink) and path. A path longer than 1,024 bytes is cut to that and marked truncated.
  • others: the entries and bytes owned by anyone else.
  • capped: true when 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 local sandbox is refused.

  • The image needs useradd and groupadd (package passwd), awk and GNU find. With any share it also needs setfacl and getfacl (package acl), which the default Inspect image and python:3.12-bookworm lack. Bridged members with bridged tools, such as swarm_bridged_tools(), also need curl: 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/shm or /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’s files.

  • 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 rw share 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() and codex_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-swarm group or swarm-<member> user or group, and checks that sudo -n true fails 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).