toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(260504-bw4): document SSH support in README

Browse source
This commit is contained in:
Christopher Mühl 2026-05-04 08:39:57 +00:00
parent e9154fd691
commit b2aeb2fd12
1 changed files with 45 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
README.md
View file

@ -38,6 +38,8 @@ Then add `inputs.claudebox.packages.${system}.default` to your `environment.syst
| `--check` | Verify prerequisites and exit |
| `--shell` | Drop into a bash shell instead of Claude Code |
| `--gc` | Remove stale per-project instance dirs and exit |
| `--with-ssh` | Forward $SSH_AUTH_SOCK into the sandbox (requires running ssh-agent) |
| `--ssh-key <path>` | Mount a private key file read-only into the sandbox ~/.ssh/ (repeatable) |
| `--` | Pass remaining args to Claude Code |
## Env vars
@ -65,6 +67,49 @@ CLAUDEBOX_EXTRA_ENV=MY_VAR,OTHER_VAR claudebox
All injected vars appear in the `[+]` section of the env audit.
## SSH
SSH is opt-in. By default no keys or agent socket cross the sandbox boundary, which means git push/pull over SSH remotes won't work. Two mechanisms are available — pick whichever matches your workflow.
### `--with-ssh` (agent forwarding)
Forwards `$SSH_AUTH_SOCK` into the sandbox so any keys loaded in your ssh-agent are usable inside. Your private key files are never mounted; only the agent socket is.
Start an agent before launching claudebox. The agent dies with the shell that started it, so don't expect it to survive across terminals.
Bash:
```bash
eval "$(ssh-agent)"
ssh-add ~/.ssh/id_ed25519
claudebox --with-ssh
```
Fish:
```fish
eval (ssh-agent -c)
ssh-add ~/.ssh/id_ed25519
claudebox --with-ssh
```
If `--with-ssh` is passed but no agent is running, claudebox warns and continues without forwarding.
### `--ssh-key <path>` (explicit key files)
Mounts a specific private key (and matching `.pub`, if present) read-only into the sandbox at `~/.ssh/<basename>`. Repeatable — pass it multiple times for multiple keys.
```bash
claudebox --ssh-key ~/.ssh/id_ed25519
claudebox --ssh-key ~/.ssh/id_work --ssh-key ~/.ssh/id_personal
```
Prefer this when you don't have an agent running, or when you want to scope exactly which keys the sandbox can use regardless of what's loaded in the agent.
### known_hosts
When either flag is active, `~/.ssh/known_hosts` is mounted read-only (if it exists) so SSH host verification works without prompting.
Both flags can be combined.
## How it works
```