From f747daf3486262ee44feb4a6294514c5d696cefb Mon Sep 17 00:00:00 2001
From: "J.Jason" <130959319+JJasonSun@users.noreply.github.com>
Date: Tue, 22 Sep 2026 22:56:46 +0800
Subject: [PATCH] docs: verify Cursor sandbox network troubleshooting

---
 docs/install/troubleshooting.md               | 99 +++++++++----------
 .../skills-sh-skill/scripts/check-skill.mjs   |  4 +-
 .../skills-sh-skill/test/check-skill.test.js  | 10 ++
 3 files changed, 62 insertions(+), 51 deletions(-)

diff --git a/docs/install/troubleshooting.md b/docs/install/troubleshooting.md
index 2d9760f..d11ee31 100644
--- a/docs/install/troubleshooting.md
+++ b/docs/install/troubleshooting.md
@@ -7,75 +7,74 @@ fails in a local agent environment.
 
 ### Symptoms
 
-In Cursor, CALL-E setup may fail even though the local machine has normal network
-access. Common symptoms include:
+A request works in your terminal but fails in the Cursor agent shell with
+`CONNECT tunnel failed, response 403`. The CALL-E CLI may also report
+`fetch failed`.
 
-- `npx skills add https://github.com/CALLE-AI/call-e-integrations --skill calle -g`
-  fails because sandboxed Git cannot write hooks.
-- `calle auth login` fails with a generic `fetch failed` error.
-- A direct network check fails with:
+### Check the sandbox
 
-  ```text
-  curl: (56) CONNECT tunnel failed, response 403
-  ```
+In Cursor 3.21.16, the setting is under **Settings → Agents → Execution and
+Approvals → Run Mode**. Keep **Auto-Review (with Sandbox)** enabled while checking
+network access. Run this in the agent shell:
 
-- The agent environment reports limited or allowlist-only network access.
-
-### Cause
-
-The `403` is returned by Cursor's sandbox network gate before the request reaches
-CALL-E. It is not a CALL-E authentication failure and does not mean the CALL-E
-server rejected the user.
-
-The sandboxed agent shell may block outbound HTTPS connections to
-`https://seleven-mcp-sg.airudder.com`, which prevents the CLI from starting the
-brokered OAuth flow.
-
-### Fix
+```bash
+printf "CURSOR_SANDBOX=%s\n" "$CURSOR_SANDBOX"
+curl -sS --connect-timeout 10 --max-time 20 -o /dev/null -w "HTTP %{http_code}\n" https://seleven-mcp-sg.airudder.com/
+```
 
-Change the local Cursor agent execution mode so commands are not running in the
-restricted sandbox:
+On macOS, `CURSOR_SANDBOX=seatbelt` identifies the sandbox. If curl reports a
+CONNECT 403 there but reaches the same host in your terminal, check the sandbox's
+domain policy. A generic `fetch failed` alone does not identify the cause.
 
-1. Open Cursor Settings.
-2. Go to **Agents**.
-3. In **Auto-Run**, open **Auto-Run Mode**.
-4. Select **Run Everything (Unsandboxed)**.
+### Allow the CALL-E host
 
-After switching to a non-sandboxed mode, retry the CALL-E login or setup check.
+Using your editor, add the CALL-E host to the workspace's
+`.cursor/sandbox.json`. If the file already exists, merge the entry into its
+`networkPolicy.allow` list without replacing other settings:
 
-### Cursor Setting Screenshot
+```json
+{
+  "networkPolicy": {
+    "default": "deny",
+    "allow": ["seleven-mcp-sg.airudder.com"]
+  }
+}
+```
 
-![Cursor Auto-Run Mode setting showing Run Everything Unsandboxed](../assets/troubleshooting/cursor-agent-execution-mode.png)
+This keeps the sandbox enabled. Existing deny rules and organization policies
+can still block the host; see Cursor's
+[sandbox configuration reference](https://cursor.com/docs/reference/sandbox).
+Retry the curl check. An HTTP 404 from this root URL still confirms that HTTPS
+reached the server; it does not verify authentication.
 
-### Verify
+### Verify the CLI through the sandbox proxy
 
-Outside the restricted sandbox, follow
+If curl connects but the Node CLI still reports `fetch failed`, Node may not be
+using the sandbox's proxy. Follow
 [CLI entry point selection](../../packages/cli/docs/cli-reference.md#selecting-the-cli-entry-point)
-and prepare the launcher and `request.json`. Use each array below as `argv`:
-
-```json
-["auth", "login"]
-```
-
-```json
-["auth", "status", "--json"]
-```
+to prepare the trusted launcher and a `tools-request.json` with this `argv`:
 
 ```json
 ["mcp", "tools"]
 ```
 
-Confirm that authentication is usable and that the tool list includes:
+With an existing CALL-E login, run:
 
-```text
-plan_call
-run_call
-get_call_run
+```bash
+NODE_USE_ENV_PROXY=1 node run-agent-command.mjs tools-request.json
 ```
 
-If the same URL works from the user's terminal but fails only inside the Cursor
-agent shell, the issue is the Cursor sandbox policy rather than CALL-E service
-availability.
+This asks Node to use the proxy environment supplied by the sandbox. Keep TLS
+certificate verification enabled. The environment variable requires a Node
+version that supports it; see the
+[Node reference](https://nodejs.org/api/cli.html#node_use_env_proxy1).
+A successful response has `ok: true` and lists `plan_call`, `run_call`, and
+`get_call_run` among its tools.
+
+These steps were tested on macOS with Cursor 3.21.16, Node 26.8.2, and CALL-E CLI
+0.5.2, using an existing login. The domain entry resolved curl's CONNECT 403;
+`NODE_USE_ENV_PROXY=1` also resolved the CLI's `fetch failed`. This check does not
+cover a fresh OAuth login or skill installation.
 
 ## Run CALL-E from Node on Windows
 
diff --git a/packages/skills-sh-skill/scripts/check-skill.mjs b/packages/skills-sh-skill/scripts/check-skill.mjs
index e6341f1..63d6df1 100644
--- a/packages/skills-sh-skill/scripts/check-skill.mjs
+++ b/packages/skills-sh-skill/scripts/check-skill.mjs
@@ -279,7 +279,9 @@ function checkRepoDocs({ repoRoot, failures }) {
 
   if (fs.existsSync(troubleshootingPath)) {
     const troubleshooting = fs.readFileSync(troubleshootingPath, "utf8");
-    assert(troubleshooting.includes("npx skills add https://github.com/CALLE-AI/call-e-integrations --skill calle -g"), failures, "docs/install/troubleshooting.md must keep the skills.sh install example global with -g.");
+    if (troubleshooting.includes("npx skills add")) {
+      assert(troubleshooting.includes("npx skills add https://github.com/CALLE-AI/call-e-integrations --skill calle -g"), failures, "docs/install/troubleshooting.md must keep the skills.sh install example global with -g.");
+    }
   }
 }
 
diff --git a/packages/skills-sh-skill/test/check-skill.test.js b/packages/skills-sh-skill/test/check-skill.test.js
index 80cb31c..f700003 100644
--- a/packages/skills-sh-skill/test/check-skill.test.js
+++ b/packages/skills-sh-skill/test/check-skill.test.js
@@ -305,3 +305,13 @@ test("rejects bare calle and npx commands in the skill or command reference", (t
     }
   }
 });
+
+test("troubleshooting may omit installation but must keep any install example global", () => {
+  const { packageRoot, repoRoot } = createValidFixture(makeTempRoot("calle-troubleshooting-install"));
+  const doc = path.join(repoRoot, "docs", "install", "troubleshooting.md");
+  fs.writeFileSync(doc, "See the installation guide.\n");
+  assert.deepEqual(checkSkillsShSkill({ packageRoot, repoRoot }), []);
+  fs.writeFileSync(doc, "npx skills add https://github.com/CALLE-AI/call-e-integrations --skill calle\n");
+  assert.ok(checkSkillsShSkill({ packageRoot, repoRoot }).some((failure) =>
+    failure.includes("troubleshooting.md must keep the skills.sh install example global")));
+});