diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 9c28102d19a..ccc4330dca7 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -274,11 +274,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 diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index fc518e40ebf..19de6f7db73 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/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/git.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](configuration/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: diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md index 07ccf097acd..e90f441fe40 100644 --- a/content/manuals/ai/sandboxes/workflows/git.md +++ b/content/manuals/ai/sandboxes/workflows/git.md @@ -183,18 +183,29 @@ 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. +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](../configuration/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: @@ -203,7 +214,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"