A kind: os sandbox is refused
Added in 2.3
A repository with sandbox: {kind: os} can't launch unless the host can run bubblewrap (Linux) or Seatbelt (a Mac). Kraft checks the host before a launch and in kraft admin doctor, caches the answer for a minute, and ends the session as config_error with one of these messages in its log. Fix the host, then kraft item retry ID.
| The message says | Fix |
|---|---|
kind: os runs on Linux and macOS only in this release | Run the repo on Linux or a Mac, or use kind: docker. |
kind: os does not run while Kraft runs as root | Run the Kraft server as an ordinary user. |
kind: os supports x86_64 and aarch64, not <arch> | Use kind: docker on this machine. |
kind: os supports arm64 and x86_64 Macs, not <machine> | Use kind: docker on this machine. |
/usr/bin/sandbox-exec is missing (it ships with macOS): use kind: docker on this Mac | Repair or reinstall macOS, or use kind: docker. |
Kraft is itself running inside a sandbox, so it cannot start one: run the Kraft server outside it | Start the server from a normal terminal or a launchd agent, not from a tool that sandboxes what it starts. |
sandbox-exec cannot start a sandbox here: <error> | The trial run of Kraft's profile failed for a reason Kraft has no fix for. Read the error, which is sandbox-exec's own. |
bubblewrap is not installed (apt install bubblewrap) | Install bubblewrap with your package manager. |
sh is not installed on this host (the `kraft` shim needs it), and the same for curl, or sh and curl are not installed ... | Install what it names. |
bwrap --help failed: <error> | Fix the bwrap on PATH so that bwrap --help runs. |
this bubblewrap lacks <flags>: install a newer bubblewrap | Install a newer bubblewrap. It must have --size, --disable-userns, --as-pid-1, --cap-drop, --seccomp and --die-with-parent. |
bubblewrap cannot create a user namespace here: sysctl user.max_user_namespaces=15000 | Run that sysctl as root, and persist it in /etc/sysctl.d/. |
bubblewrap cannot create a user namespace here: sysctl kernel.unprivileged_userns_clone=1 | Run that sysctl as root, and persist it in /etc/sysctl.d/. |
bubblewrap cannot create a user namespace here: install bubblewrap's AppArmor profile, or sysctl kernel.apparmor_restrict_unprivileged_userns=0 | Install the distribution's bubblewrap AppArmor profile, which is the narrow fix. Setting the sysctl to 0 lifts the restriction for every program on the host, so persist it in /etc/sysctl.d/ only if you accept that. |
bubblewrap cannot start a sandbox here: <error> | The trial run, under the seccomp filter a session loads, failed for a reason Kraft has no fix for. Read the error, which is bwrap's own. |
These are refusals of a command or a path, with the same config_error:
| The message says | Fix |
|---|---|
'<command>' not found on the Kraft server's PATH; add its directory to the PATH the server starts with (expose does not add to PATH) | The sandbox searches /opt/kraft/bin, then the server's PATH, never expose. Put the command's directory on the PATH the server starts with (a service's is in its unit), then restart the server. |
'<command>' not found: <path> does not exist | A path-named command (./gradlew) isn't where it says. Fix the command, or commit the file it names. |
<command> leads to <path>, outside the sandbox's view; add its directory to the sandbox's expose list | A path-named command (./gradlew) is a symlink out of the worktree. Expose the target's directory. |
cannot show <path> to the sandbox: ...; add its toolchain with expose | The command's directory is protected (your home directory itself, ~/.ssh), and expose can't add it. Move the command to another directory on PATH, which is mounted by itself. |
<path> needs '<name>', which is not on the Kraft server's PATH; add its directory to the PATH the server starts with | A script's #!/usr/bin/env <name> is looked up on the server's PATH. Put the interpreter's directory there, then restart the server. |
<path> needs <name>, which does not exist | A script's #! names an absolute interpreter that isn't on this host. Install it or fix the #! line. |
<path> is under /usr or /etc, which every os sandbox mounts | A protected path (your Kraft home, or the run or config directory KRAFT_RUN_DIR or KRAFT_CONFIG_DIR names) lies under /usr or /etc, which a kind: os sandbox always shows. Move it out. |
Kraft's python prefix cannot be shown to the sandbox: ... | The system python3 is missing or older than 3.10, so the sandbox needs Kraft's own interpreter, whose prefix is protected. Install Python 3.10 or newer under /usr, or install Kraft elsewhere. |
expose '<path>' is protected: ..., when repos.yaml loads | The entry is or holds a protected path, and the entry doesn't load. Remove it or narrow it. See Protected paths. |
expose path <entry>: ..., or expose path <path> does not exist, at launch | Remove the entry or fix it. See Protected paths. |
A command that isn't found once the session runs exits 127 with kraft: a command was not found inside the os sandbox; add its directory to the sandbox's expose list: a tool the repo's own commands call (uv in ~/.local/bin, a Nix CLI) is in the same position. Add its directory to expose. A library a toolchain loads from outside /usr needs the same: Homebrew's bash fails on libreadline until /opt/homebrew is exposed.
After you edit expose, run kraft item retry ID --sandbox-from-config --yes to give the item the edited list.
Exit 126 (kraft: <command> is not executable) is only a PermissionError on the exec, the file's mode; any other exec failure is 127. A command that can't start sends no started byte, so the session ends as config_error (launch_failed), not as a task failure. See The OS sandbox.
Sandbox and Kit stops
Find the reason a sandboxed work item stopped, whether a sandbox with no network policy, the sandbox's memory limit, a Kit Kraft won't run, a workspace member Kraft can't check out, or a nested git repository Kraft didn't create, and the fix for each.
Doctor failures
What each failing or warning row of kraft admin doctor means and how to clear it.