docs: document opt-in SSH agent forwarding

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

@@ -274,11 +274,37 @@ 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 off by default. To use your host SSH agent for Git
+authentication or commit signing inside a sandbox, turn it on:
+
+```console
+$ sbx settings set ssh.agentForwardingEnabled true
+```
+
+When forwarding is enabled, Docker Sandboxes uses the `SSH_AUTH_SOCK` value
+from the client that creates, starts, or joins each sandbox. It forwards that
+agent into the sandbox and sets `SSH_AUTH_SOCK` there.
+
+If your agent uses a custom socket path, such as the 1Password SSH agent,
+configure a fixed path:
+
+```console
+$ sbx settings set ssh.agentSocketPath /path/to/agent.sock
+```
+
+An empty `ssh.agentSocketPath` uses each client's current `SSH_AUTH_SOCK`
+instead. You can also configure forwarding and choose between the current
+client socket and a fixed path by running `sbx setup`.
+
+Restart the daemon after changing either setting to replace forwarders for
+existing sandboxes:
+
+```console
+$ sbx daemon restart
+```
+
+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 a 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

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

@@ -233,4 +233,11 @@ environment variables or files inside the sandbox unless you explicitly set
 them. This means a compromised sandbox cannot read API keys from the local
 environment.
 
+SSH agent forwarding is also off by default. When you opt in, private keys
+stay on the host, but any process inside the sandbox can ask the forwarded
+agent to authenticate or sign data. Docker Sandboxes validates the upstream
+socket as an SSH agent before forwarding requests. If forwarding is disabled,
+the settings can't be read, or no client socket is available, the sandbox
+doesn't receive access to an SSH agent.
+
 For how to store and manage credentials, see [Credentials](../configuration/credentials.md).

content/manuals/ai/sandboxes/troubleshooting.md

@@ -273,6 +273,17 @@ the command again:
 Docker Sandboxes can sign Git commits with SSH keys from your host agent.
 For setup steps, see [Commit signing](workflows/git.md#commit-signing).
 
+Confirm that forwarding is enabled:
+
+```console
+$ sbx settings get ssh.agentForwardingEnabled
+```
+
+If you configured `ssh.agentSocketPath`, confirm that it points to your active
+host agent socket. An empty value uses the `SSH_AUTH_SOCK` from the client that
+started or joined the sandbox. After changing either setting, run
+`sbx daemon restart`.
+
 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/git.md

@@ -183,18 +183,27 @@ yourself after reviewing the changes.
 
 ## 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.
+Sandboxes can 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. On your host, turn on SSH agent forwarding:
+
+   ```console
+   $ sbx settings set ssh.agentForwardingEnabled true
+   $ sbx daemon restart
+   ```
+
+   Forwarding is off by default. If you use a custom SSH agent socket, first
+   [configure its path](../configuration/credentials.md#ssh-agent).
+
+2. Make sure the signing key is loaded in your host 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:
 
@@ -203,7 +212,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"