docs: document sandbox SSH forwarding

content/manuals/ai/sandboxes/security/credentials.md

@@ -2,7 +2,7 @@
 title: Credentials
 weight: 20
 description: How Docker Sandboxes handle API keys and authentication credentials for sandboxed agents.
-keywords: docker sandboxes, credentials, api keys, authentication, proxy
+keywords: docker sandboxes, credentials, api keys, authentication, proxy, ssh agent, secrets
 ---
 
 {{< summary-bar feature_name="Docker Sandboxes sbx" >}}
@@ -114,6 +114,20 @@ $ echo "$(gh auth token)" | sbx secret set -g github
 This is useful for agents that create pull requests, open issues, or interact
 with GitHub APIs on your behalf.
 
+### SSH agent
+
+If your host has an SSH agent and `SSH_AUTH_SOCK` is set, Docker Sandboxes
+forwards the agent into the sandbox and sets `SSH_AUTH_SOCK` there. The
+private keys stay on your host. Processes inside the sandbox can request
+signatures from the forwarded agent, but they can't read or copy the private
+key.
+
+Use SSH agent forwarding for Git operations over SSH and SSH-based commit
+signing. The signing key must be loaded in the host SSH agent for sandboxed
+commit signing to work. Outbound SSH connections are still subject to sandbox
+network policy. For details, see
+[Signed commits](../usage.md#signed-commits).
+
 ## Environment variables
 
 As an alternative to stored secrets, export the relevant environment variable

content/manuals/ai/sandboxes/troubleshooting.md

@@ -2,7 +2,7 @@
 title: Troubleshooting
 weight: 60
 description: Resolve common issues when using Docker Sandboxes.
-keywords: docker sandboxes, sbx, troubleshooting, diagnostics, reset
+keywords: docker sandboxes, sbx, troubleshooting, diagnostics, reset, network policy, git, ssh
 ---
 
 {{< summary-bar feature_name="Docker Sandboxes sbx" >}}
@@ -135,20 +135,46 @@ $ git worktree remove .sbx/<sandbox-name>-worktrees/<branch-name>
 $ git branch -D <branch-name>
 ```
 
-## Signed Git commits
+## Sandbox commits aren't signed
 
-Agents inside a sandbox can't sign commits because signing keys (GPG, SSH)
-aren't available in the sandbox environment. Commits created by an agent are
-unsigned.
+Docker Sandboxes can sign Git commits with SSH keys from your host agent.
+For setup steps, see [Signed commits](usage.md#signed-commits).
 
-If your repository or organization requires signed commits, use one of these
-workarounds:
+If `ssh-add -L` prints `The agent has no identities.`, the sandbox can reach
+the forwarded agent, but the host agent doesn't have a loaded key. Load the
+signing key into your host SSH agent:
 
-- **Commit outside the sandbox.** Let the agent make changes without
-  committing, then commit and sign from your host terminal.
+```console
+$ ssh-add ~/.ssh/id_ed25519
+```
 
-- **Sign after the fact.** Let the agent commit inside the sandbox, then
-  re-sign the commits on your host:
+If commit signing works on the host but fails in a sandbox, check whether Git
+is configured to sign with a host file path such as
+`/Users/me/.ssh/id_ed25519.pub`. The sandbox uses the forwarded SSH agent, not
+the host key file path. Use the inline public key form instead:
+
+```console
+$ git config --global gpg.format ssh
+$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"
+```
+
+If Git reports that `ssh-keygen` is missing, use a sandbox template that
+includes OpenSSH client tools.
+
+If `git log --show-signature` reports that `gpg.ssh.allowedSignersFile` needs
+to be configured, Git can't verify the SSH signature locally. This verification
+config isn't required to create signed commits. GitHub uses the SSH signing
+keys configured in your GitHub account to verify commits.
+
+GPG and S/MIME signing keys aren't available inside the sandbox. If your
+repository or organization requires GPG or S/MIME signatures, or if SSH signing
+isn't configured, use one of these workarounds:
+
+- Commit outside the sandbox. Let the agent make changes without committing,
+  then commit and sign from your host terminal.
+
+- Sign after the fact. Let the agent commit inside the sandbox, then re-sign
+  the commits on your host:
 
   ```console
   $ git rebase --exec 'git commit --amend --no-edit -S' origin/main

content/manuals/ai/sandboxes/usage.md

@@ -2,7 +2,7 @@
 title: Usage
 weight: 20
 description: Common patterns for working with sandboxes.
-keywords: docker sandboxes, sbx, usage, run, policy, secrets
+keywords: docker sandboxes, sbx, usage, run, policy, secrets, branches, git, workspaces, ssh
 ---
 
 {{< summary-bar feature_name="Docker Sandboxes sbx" >}}
@@ -149,6 +149,42 @@ worktree. If that happens, commit from the worktree directory before pushing.
 See [Workspace trust](security/workspace.md) for security considerations when
 reviewing agent changes.
 
+### Signed commits
+
+Sandboxes can sign Git commits with SSH keys from your host agent. The private
+key stays on your host.
+
+On the host, load the key into your SSH agent:
+
+```console
+$ ssh-add ~/.ssh/id_ed25519
+```
+
+Inside the sandbox, check that the forwarded agent exposes the key:
+
+```console
+$ ssh-add -L
+```
+
+Configure Git globally inside the sandbox to use SSH commit signing. This
+writes to the sandbox user's Git config, not your repository's `.git/config`.
+Use an inline public key instead of a key file path, because host paths such as
+`~/.ssh/id_ed25519.pub` might not exist in the sandbox:
+
+```console
+$ git config --global gpg.format ssh
+$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"
+```
+
+Then commit as usual:
+
+```console
+$ git commit -S
+```
+
+For common signing failures, see
+[Sandbox commits aren't signed](troubleshooting.md#sandbox-commits-arent-signed).
+
 #### Cleanup
 
 `sbx rm` removes the sandbox and all of its worktrees and branches.