diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 9c28102d19a..e2c9efc5982 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -274,11 +274,31 @@ 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 enabled by default. When `SSH_AUTH_SOCK` is set, +Docker Sandboxes uses the 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 exposes a stable socket path, such as the 1Password SSH agent, +configure that path for every sandbox: + +```console +$ sbx settings set ssh.agentSocketPath "$SSH_AUTH_SOCK" +``` + +An empty `ssh.agentSocketPath`, which is the default, uses each client's +current `SSH_AUTH_SOCK` instead. The `ssh.agentForwardingEnabled` setting is a +boolean that turns forwarding on or off. + +After changing forwarding or the socket selection, restart the daemon so +existing sandboxes use the new configuration: + +```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 diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 8515413c6b2..3993242c53e 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -233,4 +233,10 @@ 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 enabled by default. Private keys stay on the host, but +any process inside the sandbox can ask the forwarded agent to authenticate or +sign data. Docker Sandboxes forwards only sockets it recognizes as SSH agents. +A sandbox receives no SSH agent when forwarding is disabled, the configuration +is unavailable, or the selected socket can't be used. + For how to store and manage credentials, see [Credentials](../configuration/credentials.md). diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index fc518e40ebf..94cc37389f1 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). +Forwarding is enabled by default. Confirm that it hasn't been disabled and +check whether a fixed socket path is configured: + +```console +$ sbx settings get ssh.agentForwardingEnabled +$ sbx settings get ssh.agentSocketPath +``` + +If you use each client's current `SSH_AUTH_SOCK`, reconnect from a shell where +it points to the intended agent. If `ssh.agentSocketPath` returns a path, +confirm that it points to an active host agent. After changing forwarding or +the socket selection, 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: diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md index 07ccf097acd..b1ce79eda1d 100644 --- a/content/manuals/ai/sandboxes/workflows/git.md +++ b/content/manuals/ai/sandboxes/workflows/git.md @@ -183,11 +183,13 @@ 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. +SSH agent forwarding is enabled by default. When `SSH_AUTH_SOCK` is set, +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. If +you turned off forwarding or use a fixed SSH agent socket, see +[SSH agent configuration](../configuration/credentials.md#ssh-agent). -1. On your host, make sure the signing key is loaded in your SSH agent: +1. Make sure the signing key is loaded in your host SSH agent: ```console $ ssh-add ~/.ssh/id_ed25519