---
phase: 260504-bw4
plan: 01
subsystem: sandbox/ssh
tags: [ssh, bwrap, security, opt-in]
dependency_graph:
  requires: []
  provides: [ssh-agent-forwarding, ssh-key-mounts, sandbox-ssh-awareness]
  affects: [claudebox.sh, README.md]
tech_stack:
  added: []
  patterns: [opt-in SSH via bwrap --bind/--ro-bind, conditional SANDBOX.md generation]
key_files:
  modified:
    - claudebox.sh
    - README.md
decisions:
  - SSH is opt-in: no keys or sockets cross the sandbox boundary without explicit flags
  - --with-ssh validation: silently degrades to no-op with warning if ssh-agent is not running
  - SANDBOX.md uses unquoted heredoc with pre-composed variables for conditional content
  - known_hosts mounted once if either SSH mechanism is active (shared between --with-ssh and --ssh-key)
metrics:
  duration: 8min
  completed: 2026-05-04
  tasks: 3
  files: 2
---

# Quick Task 260504-bw4: Add SSH Support to claudebox Summary

One-liner: Opt-in SSH via `--with-ssh` (agent socket forwarding) and `--ssh-key` (explicit key file mounts), with audit/dry-run/SANDBOX.md integration and README documentation.

## Tasks Completed

| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | Implement --with-ssh and --ssh-key flag parsing + bwrap mounts | 41ebf10 | claudebox.sh |
| 2 | Make SANDBOX.md conditional on SSH activation | e9154fd | claudebox.sh |
| 3 | Document SSH support in README.md | b2aeb2f | README.md |

## What Was Built

**claudebox.sh** now accepts two new flags:

- `--with-ssh`: validates `$SSH_AUTH_SOCK` is a real socket, adds `--bind $SSH_AUTH_SOCK $SSH_AUTH_SOCK` and `--setenv SSH_AUTH_SOCK` to bwrap args, degrades gracefully with a warning if no agent is running.
- `--ssh-key <path>`: repeatable, validates file exists+readable, mounts key (and `.pub` if present) read-only into `~/.ssh/<basename>` inside the sandbox.
- When either mechanism is active: `--dir ~/.ssh` is added, and `~/.ssh/known_hosts` is mounted read-only if it exists on the host.
- Audit display shows SSH mounts in the Mounts section.
- `--dry-run` output mirrors all SSH bwrap flags.
- SANDBOX.md is now generated conditionally: no-SSH mode lists SSH keys in restrictions and recommends HTTPS; SSH-active mode drops that restriction, adds a `## SSH` section describing which mechanisms are active, and says SSH remotes work.

**README.md** gains two flag table rows and a `## SSH` section covering both mechanisms, bash/fish agent setup, the agent-lifetime caveat, explicit key usage, and the known_hosts note.

## Deviations from Plan

None - plan executed exactly as written.

## Threat Flags

No new threat surface introduced. SSH flags are opt-in and explicitly documented. The agent socket bind is scope-limited to `--bind $SSH_AUTH_SOCK $SSH_AUTH_SOCK` (only the socket path the user explicitly opts into). Key files are read-only.

## Self-Check: PASSED

- claudebox.sh: FOUND
- README.md: FOUND
- 41ebf10 (Task 1): FOUND
- e9154fd (Task 2): FOUND
- b2aeb2f (Task 3): FOUND