diff --git a/README.md b/README.md
index b727cf5..745347c 100644
--- a/README.md
+++ b/README.md
@@ -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
 
 ```