Sandboxing
Skep can run workers under the host OS sandbox backend. The sandbox is defense in depth: patch approval and re-verification still matter, but sandboxing gives a physical boundary for network and filesystem writes while the worker runs.
Backends
| Platform | Backend | Status |
|---|---|---|
| macOS | Seatbelt (sandbox-exec) |
Supported when the host process may apply profiles |
| Linux | Bubblewrap (bwrap) |
Supported when bwrap is installed and the probe succeeds |
| Linux (opt-in) | podman (sandbox_backend=podman) |
Runs with SELinux labelling disabled for the container; the probe proves a mount round trip |
| Other | none | Unavailable |
Skep probes the backend before launch. If sandboxing is requested but no backend can be applied, worker launch fails instead of silently running unsandboxed.
Filesystem Boundary
The sandbox mounts the root filesystem read-only and binds only the intended writable roots back as writable:
- the worker workspace (its private
TMPDIRlives inside it) - the run's own result directory (
results/<task_id>/, where--outpoints); no run can write another run's result, and the supervisor rejects (and records on the run) an envelope whosetask_idis not the run's - the worktree's own git metadata and the repo's
objects/— enough forgit add/git commit; the repo'shooks/,configandrefs/stay read-only, and skep's own host-side git runs with hooks and fsmonitor off. On macOS a worker'sgit committherefore printserror: Unable to create '<repo>/.git/packed-refs.lock': Operation not permittedand exits 0: the commit succeeded, and the message is expected. - any explicit extra writable roots from supervisor configuration
Shared temp dirs (/tmp, /var/folders) are not writable, and a run whose
skep home lies inside a writable root is refused. So every temp variable a
run's tools read points inside the workspace: TMPDIR, zsh's TMPPREFIX,
CLAUDE_CODE_TMPDIR for the claude_code engine (Claude Code's Bash tool
ignores TMPDIR), and on macOS XDG_RUNTIME_DIR (on Linux bubblewrap gives each run a private
/tmp instead).
This blocks writes outside the workspace/results boundary. Reads are open so
the toolchain works, except the secret floor, which is hidden on every
backend: ~/.ssh ~/.aws ~/.gnupg ~/.config/gh ~/.netrc ~/.git-credentials ~/.docker/config.json ~/.kube ~/.secrets ~/.config/gcloud ~/.azure ~/.pypirc ~/.vault-token ~/.terraform.d/credentials.tfrc.json ~/.config/op ~/.cargo/credentials{,.toml} ~/.claude.json ~/.password-store, the shell rc
files (~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc ~/.zshenv ~/.zprofile)
and REPL histories (~/.bash_history ~/.zsh_history ~/.python_history ~/.node_repl_history ~/.psql_history ~/.mysql_history ~/.sqlite_history),
and the skep home's serve.env, supervisor/serve-token,
supervisor/*-secret, supervisor/llm-secret*, supervisor/audit/ (every
run's audit trail) and supervisor/chat-attachments/. One carve-out: a
worker whose caste calls the LLM (coding, document, reviewer) reads
llm-secret and the active provider profile's llm-secret-<id>, its own
model credential; external engines and every other sandboxed lane see no LLM
key. With the provider-key relay on (provider_key_relay, ADR 0062; off by
default), a builtin worker gets no carve-out: its model calls go through a
token-checked route on its run's filtering proxy, which adds the key, so the
key files stay masked and no variable carrying the key reaches its env. Not
relayed: bedrock (SigV4 signs with the key), a provider with no key, and the
external engines, which keep their own auth env (skep doctor says which). supervisor/supervisor.sqlite3 stays readable (that worker reads its
provider settings from it). So does ~/.npmrc (npm install): the sandbox
leaves it readable, while the policy floor still refuses every Queen and
worker read tool on it (sandbox.SANDBOX_READABLE_SECRETS). The engine
logins — ~/Library/Keychains, ~/.claude/.credentials.json,
~/.codex/auth.json — are masked like every other credential (W33): an
external engine's config dir is redirected per run and it authenticates only
from its auth env (CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY,
OPENAI_API_KEY); a dispatch without one is refused (NO AUTH ENV). One
exception, opt-in per project: a codex run with no OPENAI_API_KEY may use
the operator's ChatGPT plan login through an access-token-only, read-only
copy that only that run's sandbox can read (it sits in the masked audit dir
and is bound back for its own run) and that is deleted when it ends — the
real ~/.codex/auth.json stays masked and the refresh token never enters the
sandbox (codex-chatgpt-login.md).
Everything else outside the workspace stays readable, including other runs' worktrees under the skep home: no profile masks them. Treat a sandboxed worker as able to read any file the lists above do not name.
On Linux the worker also gets its own PID and IPC namespaces and an empty
/run (no host D-Bus or systemd sockets).
Unix sockets on Linux: a read-only bind does not stop connect(), so
bubblewrap closes a socket only by hiding it. Hidden in every network mode:
everything under /tmp and /run (fresh tmpfs: the session D-Bus,
systemd, rootless Docker and podman, gpg-agent's runtime dir, most
ssh-agents); the agent places under every home (~/.ssh, ~/.gnupg and
sandbox.AGENT_SOCKETS: ~/.1password, ~/.bitwarden-ssh-agent.sock,
~/.docker/desktop, ~/.docker/run, ~/.colima, ~/.lima, ~/.rd/docker.sock,
~/.orbstack/run, ~/.local/share/containers/podman/machine); the socket
serve's own $SSH_AUTH_SOCK, or a unix:// DOCKER_HOST or
CONTAINER_HOST, names; and every socket inside a read-only root the sandbox
binds (the repo's git dir: git's fsmonitor socket). A worker still uses
sockets in its own roots, and a proxied run its proxy bridge.
Still reachable on Linux, by the kernel's Landlock ABI (see Landlock below),
and stated by skep doctor in its sandbox line:
- ABI 9 and later: no socket the worker did not make, except those inside its own writable roots. Neither the masks nor Landlock touch a descriptor the worker already holds when it starts.
- ABI 6 to 8: a unix socket at any other path outside
/tmpand/run(an app socket somewhere under a home), in every network mode; on podman, any such path under the host dirs it binds (/home /var /etc /usr /opt). - Below ABI 6, or Landlock off: that path socket, and an abstract socket (a
name starting with a NUL byte: the session D-Bus where it listens
abstractly, X11's
@/tmp/.X11-unix/X0) in a bubblewrap allow-all run. Abstract sockets belong to the network namespace, so deny-all and proxied runs (--unshare-net) cannot reach them, nor can any podman run (it always gets its own network namespace).
Bubblewrap has no socket filter of its own. A seccomp filter (--seccomp)
cannot do it either: classic BPF sees only the connect() arguments, not
the address the pointer leads to, so it cannot tell an abstract name from a
path.
Landlock (Linux)
Landlock, the kernel's unprivileged access control, closes what the masks
cannot. Where it is applied: inside the sandbox, by skep.landlock, a
standard-library step (ctypes and syscall(), no dependency) that bubblewrap
or podman runs first; it sets PR_SET_NO_NEW_PRIVS, restricts itself and
then execs the worker, which inherits the restriction and cannot lift it.
In a proxied run it runs after skep.netshim (which needs the proxy
bridge) and before the worker. It never runs in serve: serve only reads the
kernel's Landlock ABI number when it writes the run's profile and puts the
step, with what it must scope, into the argv (kept as evidence).
What is scoped, by the ABI the running kernel reports:
- ABI 6 and later (Linux 6.12+):
LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET. The worker cannot connect to an abstract socket made outside its own process tree; ones it makes itself still work. - ABI 9 and later:
LANDLOCK_ACCESS_FS_RESOLVE_UNIX. The worker connects to a path socket only inside its writable roots (workspace, results, git metadata, caches) or one it made itself; any other path socket, listed or not, is refused withEACCES. - With
RESOLVE_UNIXthe step also handlesLANDLOCK_ACCESS_FS_REFERand grants it on/: the kernel otherwise refuses every cross-directory rename and hard link once any filesystem right is handled. Its no-gain rule still refuses moving or linking a socket into a writable root. No other right is handled: file access stays the mount layout's job.
On an older kernel, or with Landlock disabled at boot, serve leaves the step
out, skep doctor says so in one line, and runs carry on exactly as before
with the gaps below. If the kernel reports the ABI but applying it fails,
the run fails: it never runs unscoped while the doctor says scoped.
Podman runs the same step inside the container (its default seccomp profile allows the Landlock calls). Abstract sockets cannot reach a podman run anyway (its own network namespace), so there it is the path-socket right that matters.
Landlock only ever narrows. Every bubblewrap and podman mask above stays: they also hide what a socket file reveals by being read, and they are the wall on a kernel without Landlock.
No sandbox nests inside it. The kernel refuses mount changes to a
Landlock-restricted process, even in a new user namespace, so a bubblewrap
started inside the worker fails (bwrap: Failed to make / slave: Operation not permitted). External engines that would start one get theirs turned
off (ES-F220, ES-F221): codex exec --sandbox danger-full-access, and
Claude Code --settings '{"sandbox": {"enabled": false}}' (its Bash
sandbox is bubblewrap, and the operator's or the repo's own settings may
turn it on). skep's sandbox is their wall (ADR 0047): external engines are
always run in it (v94-F4), and the codex, aider and pi workers refuse to
start unless the spawner marked their launch as sandboxed (SKEP_SANDBOX). On macOS the same
holds for another reason: sandbox-exec inside a Seatbelt-sandboxed
process fails with sandbox_apply: Operation not permitted, so an engine's
own Seatbelt cannot nest inside skep's. With the engine's sandbox off, it
never tries. aider and pi start no sandbox of their own.
Loopback
Loopback is closed to a sandboxed worker by default. A run reaches a port on this host only when it is:
- its own model provider's port, when that provider is local (for example
Ollama on
127.0.0.1:11434), or - a port the project policy lists in
loopback_ports.
Serve's port is never reachable, even when a project lists it: 8765,
$SKEP_SERVE_URL's port, and the port skep serve records in
supervisor/serve-port under the same home, so a CLI skep run refuses it
too. The dispatch card and manifest show the loopback ports a run gets.
To open a port for a project's workers (a local database or test server):
skep project setup /path/to/repo --loopback-port 5432
From chat, setup_project with policy_overrides: {"loopback_ports": [5432]}
(it shows a card). Ports run 1024-65535: a port below 1024 is privileged inside
bubblewrap's network namespace, netshim could not present it and the worker
would not start, so setup refuses it. A local model provider on a port below
1024 (http://localhost:80) is refused the same way on Linux: the run records
sandbox_unavailable before any worker starts, saying to move the provider to
1024 or above. HTTP to a closed port answers 403 naming the port and that
command; a raw connection on macOS fails with "Operation not permitted".
Re-verification gets the same ports the run had: the project's and its local
provider's. skep doctor and
skep policy migrate --dry-run name the projects that open none.
How each backend enforces it:
- macOS (Seatbelt): the profile refuses every connection to
localhostexcept the run's ports and the filtering proxy's port. Binding and accepting stay open (they reach nothing). Loopback HTTP goes through the proxy, so a closed port gets the explanatory403. - Linux (bubblewrap): a deny-all or domain-list run has its own network
namespace, so its loopback is not the host's. The host's loopback is
reachable only through the proxy bridge, which admits the run's ports
alone, and
skep.netshimpresents each of them on the sandbox loopback (raw TCP too). A run with no proxy (no provider, no hosts) reaches no host port. A*run shares the host network namespace: bubblewrap has no port filter there, so its loopback is the host's, serve's port included.
A Seatbelt worker connects only to unix sockets under its own writable roots
(W34): the operator's ssh-agent, Docker, gpg-agent and other local daemons are
refused in every network mode. An allow-all run may also reach
/var/run/mDNSResponder (name lookups); a deny-all or proxied run may not, so
a name cannot carry data out through the system resolver (the proxy resolves
for it; localhost resolves from /etc/hosts).
Network Modes
Skep models network access as a domain list:
- empty list: deny all outbound network
*: allow all outbound network- concrete domains: allow only those domains, when the backend can enforce it
A dispatch that names hosts adds them to the project's own (default_network,
the trusted-dev registries and remembered hosts); an explicit empty list leaves
the worker only its own model provider.
Whatever the mode, every worker env carries GIT_ALLOW_PROTOCOL=file: git
inside a worker (and every process it starts) uses only its local transport,
so a push, fetch, clone or submodule update over https, ssh or git:// fails
with "transport not allowed". That includes a package manager's git-sourced
dependencies (git+https://… in uv/pip, github: in npm) unless they are
already in the cache.
A process that clears its env (env -i git push, subprocess.run(..., env={}))
drops the variable, so skep's task worktrees carry the same rule as git
config, which git reads with an empty environment. The first time skep runs a
task in a repository it writes .git/skep-protocol-pin (protocol.allow=never,
protocol.file.allow=always) and adds one section to that repository's
.git/config:
[includeIf "gitdir:./worktrees/????????-????-7???-????-????????????*"]
path = skep-protocol-pin
It matches only a linked worktree whose git dir is named like a skep task id
(a UUIDv7): your checkout and your own worktrees read none of it, and it is
plain config every git client parses (no repository extension). To remove it:
git config --remove-section 'includeIf.gitdir:./worktrees/????????-????-7???-????-????????????*'
and delete the file; skep writes both again on its next run there. In sandbox
mode both files are read-only to the worker (it cannot edit, delete or
replace them). In workspace mode there is no sandbox: the worker can edit or
delete them, so there the rule only stops a script that clears its env and
does nothing else.
Neither carrier stops git told otherwise on its command line
(git -c protocol.allow=always), a GIT_CONFIG_* variable, a .git file
repointed at another git dir, or a fresh clone in the workspace: the network
mode above is the wall. skep's own pushes (open_pr, push_branch) run in your
checkout, which reads none of this.
macOS
For concrete domain allowlists, Seatbelt pins worker egress to Skep's loopback filtering proxy. Seatbelt enforces that the worker can only talk to the proxy; the proxy enforces the allowed domains.
Linux
Bubblewrap enforces:
- deny-all network with
--unshare-net - allow-all network by omitting
--unshare-net - concrete per-domain allowlists (v28): the netns keeps
--unshare-net(no route out), the private host directory holding the filtering proxy's AF_UNIX socket is bind-mounted in read-only, andskep.netshimpresents the proxy port on the sandbox loopback and bridges it to that socket. Egress is exactly as tight as deny-all, plus one filtered pipe — the same guarantee Seatbelt gives on macOS. --die-with-parentin every invocation. With serve's restart re-adoption on (the default, ADR 0060), bwrap's parent is a small host keeper process rather than serve, so a sandbox outlives a serve restart and is re-adopted; the keeper kills it a minute past its wall-clock budget if no serve comes back.skep serve --no-readoptmakes bwrap serve's child again.
Running With The Sandbox
Use sandbox mode explicitly:
skep run /path/to/repo "fix the failing test" --execution-mode sandbox
On Linux, install bubblewrap first:
# Fedora
sudo dnf install bubblewrap
# Ubuntu/Debian
sudo apt install bubblewrap
Troubleshooting
If skep run --execution-mode sandbox fails before the worker starts, check the
sandbox probe:
skep doctor
Common causes:
bwrapis missing on Linux.- Bubblewrap is installed but user namespaces are disabled by host policy.
On Ubuntu 24.04 this is AppArmor's unprivileged userns restriction; a
profile for
/usr/bin/bwrapalone fixes it (seeguide-ubuntu-server.md, section 3). sandbox-execexists on macOS but the parent process is not allowed to apply Seatbelt profiles.
When you need a live provider or package registry during early setup, use an
explicitly broader policy or --execution-mode workspace for that trusted run.