# 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
- Companion secret layer: envchain-xtra
- Optional sandbox layer: nono
- 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 argv codex ~/.config/bondage/bondage.conf -- --help
bondage exec codex ~/.config/bondage/bondage.conf -- --help
```

## Wrapper rule

Shell wrappers should stay thin. A thin wrapper should do little more than call:

```sh
bondage exec <profile> ~/.config/bondage/bondage.conf -- "$@"
```