sandboxes: document opt-in SSH agent forwarding

SSH agent forwarding is no longer inherited implicitly from the daemon's
environment. It requires explicit opt-in via ssh.agentForwardingEnabled,
and each sandbox uses the client's SSH_AUTH_SOCK on create, start, or
join, with ssh.agentSocketPath as an optional fixed override.

Follows docker/sandboxes#5045.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ilopezluna

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

@@ -271,11 +271,35 @@ 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.
+SSH agent forwarding is disabled by default. To let sandboxes use your host
+SSH agent, enable it explicitly and restart the daemon:
+
+```console
+$ sbx settings set ssh.agentForwardingEnabled true
+$ sbx daemon restart
+```
+
+With forwarding enabled, Docker Sandboxes forwards your host 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.
+
+Each sandbox uses the `SSH_AUTH_SOCK` supplied by the client that creates,
+starts, or joins it. If a sandbox picks up the wrong agent, re-enter it from
+a shell where `SSH_AUTH_SOCK` points at the intended one.
+
+To always forward a fixed socket instead — for example, the 1Password SSH
+agent — set `ssh.agentSocketPath`:
+
+```console
+$ sbx settings set ssh.agentForwardingEnabled true
+$ sbx settings set ssh.agentSocketPath "$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
+$ sbx daemon restart
+```
+
+When `ssh.agentSocketPath` is set, every sandbox uses that socket regardless
+of the client's `SSH_AUTH_SOCK`. Clearing the path switches back to the
+per-client socket; it doesn't disable forwarding.
 
 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

content/manuals/ai/sandboxes/troubleshooting.md

@@ -273,6 +273,19 @@ the command again:
 Docker Sandboxes can sign Git commits with SSH keys from your host agent.
 For setup steps, see [Commit signing](workflows.md#commit-signing).
 
+SSH agent forwarding is disabled by default. If `SSH_AUTH_SOCK` isn't set
+inside the sandbox, enable forwarding on the host and restart the daemon:
+
+```console
+$ sbx settings set ssh.agentForwardingEnabled true
+$ sbx daemon restart
+```
+
+Then re-enter the sandbox from a shell where `SSH_AUTH_SOCK` points at the
+agent that holds your keys. See
+[SSH agent](security/credentials.md#ssh-agent) for how the forwarded socket
+is selected.
+
 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:

content/manuals/ai/sandboxes/workflows.md

@@ -385,18 +385,29 @@ $ curl http://host.docker.internal:11434
 
 ## Commit signing
 
-Sandboxes forward your host SSH agent into the sandbox, so the agent can
-sign commits with your SSH key without the private key ever leaving your
-host.
+With SSH agent forwarding enabled, sandboxes forward your host SSH agent into
+the sandbox, so the agent can sign commits with your SSH key without the
+private key ever leaving your host.
 
-1. On your host, make sure the signing key is loaded in your SSH agent:
+1. Enable SSH agent forwarding, which is disabled by default, and restart the
+   daemon:
+
+   ```console
+   $ sbx settings set ssh.agentForwardingEnabled true
+   $ sbx daemon restart
+   ```
+
+   For how the forwarded socket is selected, including using a fixed socket
+   path, see [SSH agent](security/credentials.md#ssh-agent).
+
+2. On your host, make sure the signing key is loaded in your SSH agent:
 
    ```console
    $ ssh-add ~/.ssh/id_ed25519
    $ ssh-add -L  # confirm the key appears
    ```
 
-2. Inside the sandbox, configure Git to sign with SSH. Use the forwarded key
+3. Inside the sandbox, configure Git to sign with SSH. Use the forwarded key
    directly rather than a file path, since host paths don't exist inside the
    sandbox:
 
@@ -405,7 +416,7 @@ host.
    $ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"
    ```
 
-3. Sign commits as usual:
+4. Sign commits as usual:
 
    ```console
    $ git commit -S -m "feat: my change"