From b93d3c1fcf5195610bb62219bbf82ee9880e6c2f Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 5 Aug 2026 07:22:18 +0000
Subject: [PATCH] docs: add VS Code SSH config troubleshooting

VS Code can leave duplicate or malformed sandbox SSH blocks that cause host key verification failures. Document how to remove the managed blocks, regenerate the SSH setup, and reconnect.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../ai/sandboxes/integrations/vscode.md       | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md
index 396ff4ad1f1..3e82d46c674 100644
--- a/content/manuals/ai/sandboxes/integrations/vscode.md
+++ b/content/manuals/ai/sandboxes/integrations/vscode.md
@@ -54,6 +54,34 @@ settings:
 For details, see
 [microsoft/vscode-remote-release#11672](https://github.com/microsoft/vscode-remote-release/issues/11672).
 
+### SSH host key verification fails
+
+VS Code can leave duplicate or malformed `Host *.sbx` blocks in your SSH
+config after you add an SSH host. If a VS Code connection reports a
+`KnownHostsCommand` error or `Host key verification failed`, remove every SSH
+config block marked `docker sandboxes (managed)`, including the marker
+comments:
+
+```diff
+-# >>> docker sandboxes (managed) >>>
+-Host *.sbx
+-    User _default_user_
+-    ProxyCommand "sbx" ssh proxy %n
+-    ...
+-    UserKnownHostsFile "~/.ssh/sbx_known_hosts"
+-    KnownHostsCommand "sbx" ssh known-hosts %H
+-    StrictHostKeyChecking yes
+-# <<< docker sandboxes (managed) <<<
+```
+
+Then regenerate the managed block:
+
+```console
+$ sbx setup ssh
+```
+
+Reconnect to the sandbox from VS Code.
+
 ## Related
 
 - [Editor and app integrations](_index.md) — how SSH access works and how to