Troubleshooting

A kind: os sandbox is refused

Fix a work item that stopped because the host can't run a kind: os sandbox, or because a command or path a session needs isn't in the sandbox's view.

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 saysFix
kind: os runs on Linux and macOS only in this releaseRun the repo on Linux or a Mac, or use kind: docker.
kind: os does not run while Kraft runs as rootRun 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 MacRepair or reinstall macOS, or use kind: docker.
Kraft is itself running inside a sandbox, so it cannot start one: run the Kraft server outside itStart 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 bubblewrapInstall 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=15000Run that sysctl as root, and persist it in /etc/sysctl.d/.
bubblewrap cannot create a user namespace here: sysctl kernel.unprivileged_userns_clone=1Run 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=0Install 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 saysFix
'<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 existA 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 listA 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 exposeThe 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 withA 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 existA 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 mountsA 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 loadsThe 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 launchRemove 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.

Copyright © 2026