@zeroseed/boxsh

First-party Boxsh integration for ZeroSeed. It provides an explicit zs-boxsh command, the boxsh-exec Skill, and host-enforced sandboxing for model-generated shell calls.

Install

zeroseed plugin install @zeroseed/boxsh
zeroseed plugin authorize boxsh
zs-boxsh doctor

The thin entry package installs one matching @zeroseed/boxsh-* optional platform package. These packages contain the official macOS/Linux executables downloaded from the Boxsh GitHub Release. No lifecycle script or user-installed Boxsh executable is required. OpenHarmony is not supported: the signed static candidate aborts with an invalid system call on a real device.

Use

zs-boxsh run -- 'cargo test'
zs-boxsh try -- './untrusted-install.sh'

run grants write access to the current project with read-only .git, .zeroseed, and .agents paths. Before running the requested command, it verifies that the native backend can both write ordinary workspace files and reject writes to these control directories. Missing or symbolic control paths, or a backend that fails this check, produce exit code 69 without running the command. doctor reports the binary version only; it does not certify workspace protection. Workspace, wrapper, and temporary paths containing double quotes, backslashes, or control characters are rejected because the native policy format cannot safely represent them. Wrapper utilities run with a fixed system PATH, not a project-provided utility search path.

The bundled macOS 4.1.0 backend does not enforce read-only child binds under a writable parent, so run refuses that backend. This is a capability failure, not permission to execute without isolation. The wrapper never retries the requested command directly on the host.

try uses Boxsh's one-shot copy-on-write mode and does not apply changes to the original workspace. Both modes request filesystem isolation and disable network access. The command must be supplied as one quoted argument.

Configuration

[plugins.settings.boxsh]
enforce = false

With enforce = true, the Rust host resolves the registered zs-boxsh wrapper once and routes every model-generated bash call through zs-boxsh run. Missing or unsupported backends fail closed. Explicit user ! commands remain direct user actions and are not rewritten. A project can enable enforcement, but cannot disable a global enforce = true setting.

Local packaging and publishing

Download the four official v4.1.0 GitHub Release assets:

./scripts/download-release.sh v4.1.0

The script downloads the official files directly and renames them to the stable names used by the wrapper:

• boxsh-darwin-arm64
• boxsh-darwin-x64
• boxsh-linux-arm64-gnu
• boxsh-linux-x64-gnu

The downloader verifies each v4.1.0 file against the SHA-256 digest published by GitHub's Release API. A different release requires an explicit BOXSH_CHECKSUMS_FILE; unverified downloads are rejected. Deployment-target and dynamic-library compatibility remain separate release checks.

Then verify all native inputs. The repository release packager creates the thin entry package and one package per platform, and publishes every platform package before the entry package:

ZEROSEED_BOXSH_REQUIRE_ALL_NATIVE=1 node --test tests/boxsh.test.mjs
node scripts/verify-package.mjs

This package redistributes verified upstream artifacts where available.

Official v4.1.0 compatibility

• The official macOS binaries declare macOS 26.0 as their minimum deployment target.
• The official Linux x64 binary dynamically depends on glibc 2.30, libstdc++, and ncurses.
• Linux arm64 support follows the upstream Release asset and has not been independently certified by this package.
• OpenHarmony is unsupported because the signed static v4.1.0 candidate aborts on-device with an invalid system call.
• Windows is not supported.

Users on systems outside these boundaries must use a different Boxsh build; this package does not fall back to unsandboxed execution.