Security and the sandbox#
A coding agent runs commands a model chose. blyte assumes those commands can be wrong, or steered
by something the model read, and limits what they can reach. The limits are on by default and
apply to every command the model runs on the host: bash, and the gate.
What the sandbox protects
It protects your machine and your credentials from the commands. It does not review the code the model writes: a gated, sandboxed run can still produce a bad change. Review the diff.
The layers#
| layer | macOS | Linux | turn off / adjust |
|---|---|---|---|
| Writes only inside the workspace, its git directory, temp directories and tool caches | Seatbelt | Landlock (kernel 5.13+) | --sandbox=off |
Credential reads refused: ~/.ssh, ~/.aws, ~/.azure, ~/.config/gcloud, ~/.config/gh, ~/.kube, ~/.gnupg, ~/.docker/config.json, ~/.git-credentials, ~/.netrc, ~/.pypirc, cargo credentials, ~/.codex, keychains, cookies and browser profiles, and any file named .env |
Seatbelt | Landlock: reads are confined to an allow-list that leaves these out (see below) | --allow-read PATH grants one back |
| Environment: variables that look like credentials, and the AWS profile variables, are withheld from commands | yes | yes | --pass-env NAME keeps one |
| Network: commands cannot connect out | Seatbelt | Landlock (kernel 6.7+) | opt in with --network=off |
blyte's own provider keys (GEMINI_API_KEY, ANTHROPIC_API_KEY, …) and BLYTE_* variables are
always removed from commands, sandbox or not, and --pass-env cannot keep them. The one exception is
BLYTE_SESSION, the session id, which is kept so that dispatches started by a command are counted
with their session.
Writes#
Commands may write under:
- the workspace (the directory blyte runs in) and its git common directory, so commits work in a worktree;
- system temp directories (
/tmp,/var/tmp,$TMPDIR, and macOS's/private/var/folders); - tool caches under
$HOME:.cargo,.rustup,.cache,.npm,.local,Library/Caches,.gradle,.m2,go,.docker/buildx; /dev(for/dev/nulland terminals).
Anything else fails with "Operation not permitted". This is what stops a model that "fixes" a failing test by clearing a system cache, editing your shell profile or writing into another checkout.
Credential reads#
The paths in the table above are denied as file-read-data: their contents and directory listings
are refused, but stat still works, so tools that check whether .env exists (pytest does while
collecting) keep working. --allow-read PATH (repeatable) grants a path back, for a task that
legitimately needs, say, a kubeconfig.
Linux's Landlock can only allow paths, not carve holes in an allowed tree, so on Linux reads are
confined to an allow-list instead: the system directories (/usr, /lib, /bin, /etc, /opt,
/proc, /sys, /dev, /run, /var, /tmp, /snap, /nix), the workspace and the other
writable paths, and tool directories under $HOME (.cargo, .rustup, .cache, .npm, .nvm,
.pyenv, .local/bin, .local/lib, go, the git and shell configuration files, and similar). The
credential stores in the table are outside that list, so they cannot be read; --allow-read PATH
adds a path. The environment filter and the write sandbox apply on both.
The environment filter#
A variable is withheld when a _-separated part of its name is one of TOKEN, SECRET,
SECRETS, PASSWORD, PASSWD, PASS, KEY, CREDENTIAL, CREDENTIALS, AUTH, COOKIE or
SESSION (so GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY and SSH_AUTH_SOCK are withheld, while
TOKENIZERS_PARALLELISM and PATH are not), or when its value contains a URL with an inline
password (postgres://user:pass@host). blyte prints the withheld names (never values) once at
start, and --pass-env NAME keeps one.
Network (--network=off)#
For code that must not leave the machine. blyte's own model calls are unaffected; only the commands it runs are cut off.
- macOS: outbound connections to any non-local host are refused, over TCP and UDP. Localhost servers and DNS lookups still work. The Docker daemon's sockets are refused too, since a container could otherwise reach the network for the command.
- Linux (6.7+): every TCP
connect()is refused, localhost included. UDP and unix sockets (so Docker) are not covered; blyte says so when it starts.
--network=off is refused, never silently ignored, when the sandbox is off or unavailable, with
--container (set the container's network instead), or on a Linux kernel without Landlock
network support. Package installs need the network, so install dependencies before an offline run.
Containers#
With --container, commands run inside that container and the host sandbox does not apply.
Container commands never inherit the host environment. Isolate the container itself: its network
(--network none, or an internal network), its mounts and its user.
Auditing a run#
Every --report records the settings the run actually had: sandbox (seatbelt, landlock,
landlock-offline, container or off), network, allow_read, pass_env and withheld_env.
See Run reports.
Reporting a vulnerability#
See SECURITY.md.