| phase |
plan |
subsystem |
tags |
dependency_graph |
tech_stack |
key_files |
decisions |
metrics |
| 260504-bw4 |
01 |
sandbox/ssh |
| ssh |
| bwrap |
| security |
| opt-in |
|
| requires |
provides |
affects |
|
|
| ssh-agent-forwarding |
| ssh-key-mounts |
| sandbox-ssh-awareness |
|
|
|
| added |
patterns |
|
|
| opt-in SSH via bwrap --bind/--ro-bind |
| conditional SANDBOX.md generation |
|
|
|
| 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) |
|
| duration |
completed |
tasks |
files |
| 8min |
2026-05-04 |
3 |
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): FOUNDe9154fd (Task 2): FOUNDb2aeb2f (Task 3): FOUND
