Execution Tools
Tools that run commands and manage packages.
| Tool | Description |
|---|---|
run_command |
Execute a binary with argv (argv-only schema, sandbox-wrapped via go-pkg/sandbox). A plain command with no shell metacharacter (|, &&, >, *, ~) is called directly, never wrapped; pipes, redirects and globbing need an explicit ['sh','-c','...'], whose script is parsed and validated command-by-command — every binary must be a bare command name, and anything on denied_command is rejected outright. ['cd','<path>'] is special-cased and mutates Executor.WorkDir after verifying the path; rm is routed to the trash rather than deleting. Since v1.0.25 the sandbox keeps networking off by default: a command that has to reach a host (git clone / fetch / pull / push, npm / pip / brew install, go mod download, curl) sets network: true, and such a call never counts as read-only, so it always goes through the confirm gate. Commands on the read-only allowlist (configs/jsons/read_only_command.json, 410 entries, merged with read_only_command from config.json) skip the confirm gate: since v1.0.25 the binary plus up to two following arguments are matched (git status, docker ps, kubectl get, ls, ...), and a match is cancelled when any argument is a sensitive path. The dedicated read-only command tool added in v1.0.23 (run_command_readonly, which ran in parallel) was removed in v1.0.25, and the short-lived run_script never shipped in a release; use run_command, which always runs serially. To write outside $HOME the call carries write_paths, which are bound in only after a password-backed approval. sudo is rejected outright (bare or inside sh -c) with guidance to drop it and declare write_paths, which raises that sudo confirm instead. Since v1.0.11 a file watcher is rejected before it starts: --watch / --watch=..., a chokidar binary, or an npm / pnpm / yarn / bun script that resolves to one — the package script is parsed out of package.json and followed up to 5 levels, through sh -c too — because run_command waits for the process to exit and a watcher never does. The error names the one-shot build to run instead |
pkg_manage |
Drive the Linux package manager (apt / dnf / yum / pacman / apk) outside the sandbox, so the root operations bwrap cannot grant still work. action is install / remove / update / upgrade / search / info; package is a bare name — no flags, no version pin, no second package — and is required for everything except update and upgrade. Registered on Linux only. run_command cannot substitute: sudo is powerless inside bwrap. Language runtimes (node / python) → run_command with mise, fnm or uv; language-level packages (pip / npm / cargo) → run_command |