From da8d40b2b33716f682863227486d7ad0f0c73bca Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 20 Aug 2026 11:08:10 +0000 Subject: [PATCH 1/4] docs: document opt-in SSH agent forwarding SSH agent forwarding previously appeared automatic and did not document its security consent boundary or custom socket selection.\n\nDocument the opt-in setting, dynamic and fixed socket modes, restart behavior, commit-signing setup, isolation implications, and troubleshooting checks. --- .../ai/sandboxes/configuration/credentials.md | 36 ++++++++++++++++--- .../ai/sandboxes/security/isolation.md | 7 ++++ .../manuals/ai/sandboxes/troubleshooting.md | 11 ++++++ content/manuals/ai/sandboxes/workflows/git.md | 21 +++++++---- 4 files changed, 64 insertions(+), 11 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 9c28102d19a..9a66712d9ed 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/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 diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 8515413c6b2..98039f9765a 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/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). diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index fc518e40ebf..7687732a399 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/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: diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md index 07ccf097acd..c941b093b7b 100644 --- a/content/manuals/ai/sandboxes/workflows/git.md +++ b/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" From bfa4765d92a7bd1be20595a65b48fd17fd4b11ea Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 27 Aug 2026 09:30:13 +0000 Subject: [PATCH 2/4] docs: update SSH agent forwarding defaults --- .../ai/sandboxes/configuration/credentials.md | 27 ++++++++++--------- .../ai/sandboxes/security/isolation.md | 12 ++++----- .../manuals/ai/sandboxes/troubleshooting.md | 4 +-- content/manuals/ai/sandboxes/workflows/git.md | 23 ++++++---------- 4 files changed, 31 insertions(+), 35 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 9a66712d9ed..09c57756d7c 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -274,27 +274,30 @@ interact with GitHub APIs on your behalf. ### SSH agent -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: +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 uses a custom socket path, such as the 1Password SSH agent, +configure a fixed path: ```console -$ sbx settings set ssh.agentForwardingEnabled true +$ sbx settings set ssh.agentSocketPath /path/to/agent.sock ``` -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. +An empty `ssh.agentSocketPath`, which is the default, uses each client's +current `SSH_AUTH_SOCK` instead. A non-empty value overrides client sockets +with the fixed path. -If your agent uses a custom socket path, such as the 1Password SSH agent, -configure a fixed path: +To prevent sandboxes from using your SSH agent, turn off forwarding: ```console -$ sbx settings set ssh.agentSocketPath /path/to/agent.sock +$ sbx settings set ssh.agentForwardingEnabled false ``` -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`. +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: diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 98039f9765a..f32a1551009 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -233,11 +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. +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 validates the upstream socket as an SSH agent +before forwarding requests. If forwarding is disabled, the settings can't be +read, or no usable fixed or 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). diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 7687732a399..4f0252a9dbc 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -273,7 +273,7 @@ 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: +Forwarding is enabled by default. Confirm that it hasn't been disabled: ```console $ sbx settings get ssh.agentForwardingEnabled @@ -281,7 +281,7 @@ $ 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 +created, 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 diff --git a/content/manuals/ai/sandboxes/workflows/git.md b/content/manuals/ai/sandboxes/workflows/git.md index c941b093b7b..b1ce79eda1d 100644 --- a/content/manuals/ai/sandboxes/workflows/git.md +++ b/content/manuals/ai/sandboxes/workflows/git.md @@ -183,27 +183,20 @@ yourself after reviewing the changes. ## Commit signing -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. +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, 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: +1. 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 ``` -3. Inside the sandbox, configure Git to sign with SSH. Use the forwarded key +2. 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: @@ -212,7 +205,7 @@ sign commits with your SSH key without the private key ever leaving your host. $ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)" ``` -4. Sign commits as usual: +3. Sign commits as usual: ```console $ git commit -S -m "feat: my change" From 1425df255095618712f068f78edfc31db33ba13c Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 27 Aug 2026 11:05:32 +0000 Subject: [PATCH 3/4] docs: use setup for SSH agent configuration --- .../ai/sandboxes/configuration/credentials.md | 24 ++++++------------- .../manuals/ai/sandboxes/troubleshooting.md | 11 +++++---- 2 files changed, 13 insertions(+), 22 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 09c57756d7c..83604313185 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -279,28 +279,18 @@ 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 uses a custom socket path, such as the 1Password SSH agent, -configure a fixed path: +Run `sbx setup` to configure forwarding and choose which socket to use: ```console -$ sbx settings set ssh.agentSocketPath /path/to/agent.sock +$ sbx setup ``` -An empty `ssh.agentSocketPath`, which is the default, uses each client's -current `SSH_AUTH_SOCK` instead. A non-empty value overrides client sockets -with the fixed path. +From the SSH agent row, you can disable forwarding, use each client's current +`SSH_AUTH_SOCK`, or set a fixed socket path for every sandbox. A fixed path is +useful for agents that use a custom socket, such as the 1Password SSH agent. -To prevent sandboxes from using your SSH agent, turn off forwarding: - -```console -$ sbx settings set ssh.agentForwardingEnabled false -``` - -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: +Restart the daemon after changing forwarding or the socket mode to replace +forwarders for existing sandboxes: ```console $ sbx daemon restart diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 4f0252a9dbc..580ec4ac28c 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -273,15 +273,16 @@ 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: +Forwarding is enabled by default. Run `sbx setup` and confirm that forwarding +is enabled and the SSH agent row shows the intended socket mode: ```console -$ sbx settings get ssh.agentForwardingEnabled +$ sbx setup ``` -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 -created, started, or joined the sandbox. After changing either setting, run +In dynamic mode, reconnect from a shell where `SSH_AUTH_SOCK` points to the +intended agent. In fixed mode, confirm that the configured path points to your +active host agent socket. After changing forwarding or the socket mode, run `sbx daemon restart`. If `ssh-add -L` prints `The agent has no identities.`, the sandbox can reach From f84d4807b8068ebe906138cbd2fc8c91e9d13f85 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 27 Aug 2026 11:39:14 +0000 Subject: [PATCH 4/4] docs: clarify SSH agent forwarding --- content/manuals/ai/sandboxes/configuration/credentials.md | 6 +++--- content/manuals/ai/sandboxes/security/isolation.md | 7 +++---- content/manuals/ai/sandboxes/troubleshooting.md | 8 ++++---- 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 83604313185..c1c5ba3f3d0 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -285,12 +285,12 @@ Run `sbx setup` to configure forwarding and choose which socket to use: $ sbx setup ``` -From the SSH agent row, you can disable forwarding, use each client's current +In the SSH agent step, you can disable forwarding, use each client's current `SSH_AUTH_SOCK`, or set a fixed socket path for every sandbox. A fixed path is useful for agents that use a custom socket, such as the 1Password SSH agent. -Restart the daemon after changing forwarding or the socket mode to replace -forwarders for existing sandboxes: +After changing forwarding or the socket selection, restart the daemon so +existing sandboxes use the new configuration: ```console $ sbx daemon restart diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index f32a1551009..3993242c53e 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -235,9 +235,8 @@ 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 validates the upstream socket as an SSH agent -before forwarding requests. If forwarding is disabled, the settings can't be -read, or no usable fixed or client socket is available, the sandbox doesn't -receive access to an SSH agent. +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 580ec4ac28c..be68e6be9a4 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -280,10 +280,10 @@ is enabled and the SSH agent row shows the intended socket mode: $ sbx setup ``` -In dynamic mode, reconnect from a shell where `SSH_AUTH_SOCK` points to the -intended agent. In fixed mode, confirm that the configured path points to your -active host agent socket. After changing forwarding or the socket mode, run -`sbx daemon restart`. +If you use each client's current `SSH_AUTH_SOCK`, reconnect from a shell where +it points to the intended agent. If you use a fixed socket, confirm that the +configured path 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