# Skill: Sovereign Agent Sandbox & Bubblewrap Containment
Author: Drew Beyersdorf (drewsky.ai)
Version: 1.0.0
Type: agent-executable-skill
Target: Visiting AI Agents (Codex, Claude, Antigravity, Cursor, Windsurf, ChatGPT)

## Purpose
Instructs an AI agent or developer on how to safely isolate autonomous coding agents in Linux using Bubblewrap (`bwrap`), namespaces, and deterministic SHA256 receipt contracts.

---

## The Problem
When autonomous agents run shell commands without isolation:
1. They can accidentally overwrite personal home directory files, SSH keys, or bashrc.
2. They risk leaking environment secrets (.env, tokens) to cloud endpoints.
3. They can claim test passes that never actually occurred.

---

## Architectural Principles

1. **Ephemeral Root & Fake Home**: Mount system binaries (`/usr`, `/bin`, `/lib`) read-only (`--ro-bind`). Present an ephemeral tmpfs or empty directory as `$HOME`.
2. **Strict Workspace Binding**: Bind only the target repository as read-write (`--bind /path/to/repo /work`).
3. **Network Boundary**: Use `--unshare-net` by default for local code modifications and unit tests to prevent exfiltration.
4. **Deterministic Receipt (`RESULT.json`)**: Require the sandboxed command to emit a machine-readable receipt containing input/output SHA256 hashes and exit code.

---

## Reference Bubblewrap Command

```bash
#!/usr/bin/env bash
set -euo pipefail

TARGET_DIR="${1:-$PWD}"
FAKE_HOME="$(mktemp -d -t agent-home-XXXXXX)"
trap 'rm -rf "$FAKE_HOME"' EXIT

# Bubblewrap command template
bwrap \
  --ro-bind /usr /usr \
  --ro-bind /bin /bin \
  --ro-bind /lib /lib \
  --ro-bind /lib64 /lib64 2>/dev/null || true \
  --ro-bind /etc/resolv.conf /etc/resolv.conf \
  --ro-bind /etc/ssl /etc/ssl \
  --proc /proc \
  --dev /dev \
  --tmpfs /tmp \
  --bind "$FAKE_HOME" "$HOME" \
  --bind "$TARGET_DIR" /workspace \
  --unshare-all \
  --share-net \
  --die-with-parent \
  --chdir /workspace \
  bash -lc "pytest --json-report --json-report-file=RESULT.json"
```

---

## Receipt Contract Specification (`RESULT.json`)

Visiting agents MUST verify that the subagent emits this schema upon completing any execution task:

```json
{
  "schema_version": 1,
  "role": "independent_test_verification",
  "created_utc": "2026-09-08T16:00:00Z",
  "candidate": {
    "path": "/workspace/candidate.py",
    "sha256": "3c60747b..."
  },
  "tests": {
    "runs": 1,
    "methods": 68,
    "failures": 0,
    "errors": 0,
    "skipped": 0
  },
  "verdict": "PASS"
}
```

---

## Autonomous Agent Self-Audit Checklist
- [ ] Did the sandboxed process access any path outside `/workspace`? (Must be blocked).
- [ ] Are secrets (`.env`, `id_ed25519`) mounted? (Must NEVER be mounted).
- [ ] Is the resulting hash verifiable by an independent reader?