# Bondage > Bondage is a local C launcher for coding agents. It verifies exact paths and exact hashes, optionally releases secrets through envchain-xtra, optionally applies nono sandbox profiles, and keeps shell logic out of the trust boundary. ## Summary Bondage narrows the launch boundary around coding agents. The goal is not to prove that every dependency is good. The goal is to stop trusting shell aliases, mutable PATH resolution, and familiar shim names as if they were trustworthy launch identities. Bondage makes the actual launch explicit: exact absolute paths, exact hashes, optional secret release, optional sandbox policy, then exec. ## Why it exists - Coding agents should not run loose with live API keys and other secrets. - Familiar command names often hide weak dependency provenance and mutable package trees. - Broad ambient environment access is too generous by default. - Shell wrappers are useful for convenience but poor as a long-term security boundary. ## Philosophy - Use a small local launcher instead of growing more shell policy glue. - Prefer explicit trust in exact artifacts over ambient trust in names. - Let the operating system do the parts it is already better at doing. - Keep each layer narrow: - Bondage: launch verification and policy expansion - envchain-xtra: secret release - nono: sandbox enforcement ## Trust anchors - The operating system remains the strongest available layer for secret storage and signing identity. - Keychain is the preferred secret store when envchain-xtra is used. - Signing identity, where available, is useful as an approval and drift signal. - Bondage should trust exact artifacts, not a shell alias or mutable PATH result. - nono remains the enforcement layer for sandbox permissions when enabled. ## What it defends against - PATH drift and surprise binary replacement - Shell wrappers quietly becoming the policy engine - Mutable launch chains for JS-based agents - Accidental secret release to the wrong target - Confusion between sandboxed and rawdog paths ## What it does not solve - Blessing a bad npm tree in the first place - Host compromise before launch - A malicious tool you explicitly pinned and approved - Supply-chain review for dependencies you never audited - Human judgment failures about what should get secrets ## Preferred trust chain ```text shell name ↓ bondage ↓ [envchain-xtra] ↓ [nono] ↓ exact target ``` ## Installation ```sh brew tap nvk/tap brew install nvk/tap/agent-bondage brew install nvk/tap/envchain-xtra ``` ## Repositories - Homepage: https://agentbondage.org/ - Source: https://github.com/nvk/bondage - Getting Started: https://github.com/nvk/bondage/blob/main/GETTING_STARTED.md - Trust Model: https://github.com/nvk/bondage/blob/main/TRUST_MODEL.md - envchain-xtra: https://github.com/nvk/envchain-xtra - Homebrew tap: https://github.com/nvk/homebrew-tap ## Key facts - Maintainer: https://github.com/nvk - Language: C - Current launcher baseline: agent-bondage / bondage 0.3.1 - Current secret-release baseline: envchain-xtra 1.4.1 - Current sandbox baseline: nono 0.80.0 - Registry-managed Nono packs are independent dependencies; update only packs the selected profile extends and validate them with the installed Nono version - Companion secret layer: envchain-xtra - Optional sandbox layer: nono - Batch repair: `bondage repair` shows pending repins as one plan, requires a typed yes on a TTY, refuses non-interactive use and same-version fingerprint changes - GPU gate: `nono_allow_gpu = true` emits Nono's explicit `--allow-gpu` request while the selected Nono profile remains the authorization gate - Sandbox-aware doctor: inaccessible paths are reported as incomplete and never receive false repin suggestions - Formula: `agent-bondage` - Installed command: `bondage` ## Basic workflow ```sh mkdir -p ~/.config/bondage cp /path/to/bondage.conf.example ~/.config/bondage/bondage.conf bondage hash-file /absolute/path/to/tool bondage verify codex ~/.config/bondage/bondage.conf bondage chain codex ~/.config/bondage/bondage.conf -- --help bondage exec codex ~/.config/bondage/bondage.conf -- --help ``` ## Upgrade workflow Treat upgrades as launcher-policy changes. Use portable variables in docs, tickets, and transcripts so local usernames and project paths do not leak: ```sh export BONDAGE_CONF="${BONDAGE_CONF:-$HOME/.config/bondage/bondage.conf}" export NONO_PROFILE="${NONO_PROFILE:-codex}" brew upgrade nono brew cleanup nono bondage --config "$BONDAGE_CONF" repair bondage --config "$BONDAGE_CONF" doctor nono outdated nono update --dry-run nono profile show "$NONO_PROFILE" >/dev/null bondage --config "$BONDAGE_CONF" verify codex bondage --config "$BONDAGE_CONF" chain codex -- --help ``` Sandbox checks should confirm expected policy shape without exposing local project paths: ```sh for path in \ "$HOME/.ssh" \ "$HOME/.npmrc" \ "$HOME/.aws" \ "$HOME/Library/Keychains" do nono why --profile "$NONO_PROFILE" --path "$path" --op read done nono why --profile "$NONO_PROFILE" --path "$HOME/.config/nono/profiles" --op write nono why --profile "$NONO_PROFILE" --path "$HOME/.config/nono/profile-drafts" --op write ``` Expected shape: credential paths are denied, active profile writes are denied, and profile-drafts is writable only for profiles that intentionally support draft-and-promote profile edits. ## Wrapper rule Shell wrappers should stay thin. A thin wrapper should do little more than call: ```sh bondage exec ~/.config/bondage/bondage.conf -- "$@" ``` ## Hook rule Hooks can be useful as deterministic guards, but anything they print to an agent-visible transcript becomes prompt surface. Sandbox denials should be fixed in managed nono profiles and launcher config, not by injecting recovery workflows into the model context. If a hook reports a denial, keep it factual and short. Do not tell the agent to offer choices, wait, stop, or create new profile policy from hook feedback.