docs: Explain the Claude Code sandbox EPERM boundary for Unity IPC - #2015
Conversation
…exclusion boundary A sandboxed agent shell denies Unix domain socket connect/bind with EPERM, which the CLI currently misreports as a retryable i/o timeout; one full investigation (2026-07-26) chased this as an IPC bug while the Editor was healthy the whole time. The sandbox exclusion that saves game projects matches on the typed command text (`uloop *`), so this repository's dev-binary rule (`dist/<platform>/uloop`) is exactly the shape it does not cover. Record the verified invocation matrix, the remedies, and a pointer from the dev-binary validation section in AGENTS.md so the next agent reads this before re-investigating the Editor side.
|
Warning Review limit reached
Next review available in: 46 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe changes document sandbox-related failures in ChangesSandboxed Unity IPC documentation
Estimated code review effort: 1 (Trivial) | ~3 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/claude-code-sandbox.md`:
- Around line 60-63: Update the excludedCommands example in the sandbox
documentation to cover the Windows development binary documented in AGENTS.md,
such as dist/windows-amd64/uloop.exe, while retaining coverage for the Unix
dev-binary form.
- Around line 60-63: Add a brief warning under the Remedies section stating that
both options bypass Claude Code sandbox protections, and advise using only
trusted uloop dev binaries while following organizational policies for
unsandboxed execution. Keep the existing remedy instructions unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 7217a44c-6cb6-4009-9f1d-adc634361665
📒 Files selected for processing (2)
AGENTS.mddocs/claude-code-sandbox.md
| 1. Run dev-binary commands with the sandbox disabled for that command (Claude Code: | ||
| `dangerouslyDisableSandbox`; users can manage restrictions via `/sandbox`). | ||
| 2. Add the dev-binary shape to `excludedCommands` in the personal Claude Code settings, e.g. | ||
| `"dist/*/uloop *"`, alongside the existing `"uloop *"`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Cover the Windows development binary in the exclusion example.
AGENTS.md documents dist/windows-amd64/uloop.exe, but "dist/*/uloop *" only covers the extensionless Unix form. Add a Windows-specific pattern (or adjust the example) so Windows users do not remain sandboxed.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/claude-code-sandbox.md` around lines 60 - 63, Update the
excludedCommands example in the sandbox documentation to cover the Windows
development binary documented in AGENTS.md, such as
dist/windows-amd64/uloop.exe, while retaining coverage for the Unix dev-binary
form.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Files matching docs/claude-code-sandbox.md:\n'
fd -a 'claude-code-sandbox\.md$' . || true
printf '\nRelevant line context:\n'
if [ -f docs/claude-code-sandbox.md ]; then
nl -ba docs/claude-code-sandbox.md | sed -n '1,110p'
fi
printf '\nSearch for sandbox/excludedCommands in docs and related files:\n'
rg -n "dangerouslyDisableSandbox|excludedCommands|sandbox|allowUnsandboxedCommands|Claude Code" docs .uloop Packages cli 2>/dev/null || trueRepository: hatayama/unity-cli-loop
Length of output: 316
🌐 Web query:
Claude Code sandboxing excludedCommands runs outside sandbox allowUnsandboxedCommands=false
💡 Result:
When allowUnsandboxedCommands is set to false, the dangerouslyDisableSandbox escape hatch is disabled [1][2][3]. In this "strict sandbox mode," Claude is prevented from automatically retrying failed sandboxed commands outside the sandbox [1][4][5]. Consequently, any command that cannot function within the sandbox must be explicitly listed in excludedCommands to run outside of it [1][2][3]. However, the practical behavior of excludedCommands is subject to several nuances and documented issues: 1. Mandatory Inclusion: When allowUnsandboxedCommands is false, adding necessary tools (like docker) to excludedCommands is the only way to allow them to function, as the agent cannot otherwise request a one-off unsandboxed execution [4]. 2. Execution Flow: Users have reported that commands in excludedCommands may still be attempted inside the sandbox first and only run outside upon failure, or may require specific syntax (e.g., using :* to ensure matching) to be recognized correctly [6][7][8]. 3. Network Limitations: Even when a command is included in excludedCommands, it may still be subject to global network sandbox restrictions (such as blocked SSH ports), as excludedCommands primarily targets filesystem-level sandboxing [9]. 4. Security Implications of Globs: Using glob patterns (e.g., cmd:*) in excludedCommands can result in the entire shell invocation being run unsandboxed, meaning commands chained via operators like && or | may also execute outside the sandbox [10]. Due to these complexities, some users recommend using fine-grained permissions rules (e.g., Read() or Edit() with specific paths) to grant necessary access within the sandbox, rather than relying solely on excludedCommands [6][11]. [1][4][6][10][2][5][3][7][8][9]
Citations:
- 1: https://code.claude.com/docs/en/sandboxing.md
- 2: https://claude.yourdocs.dev/docs/claude-code/sandboxing
- 3: https://github.com/pleaseai/claude-code-docs/blob/4786a555/docs/sandboxing.md
- 4: [DOCS] Logic conflict between
excludedCommandsandallowUnsandboxedCommands: falseregarding Docker usage anthropics/claude-code#19135 - 5: https://docs.nvidia.com/ai-workbench/user-guide/latest/quickstart/quickstart-claude-sandbox.html
- 6: excludedCommands doesn't bypass sandbox, breaking uv and other tools with .git markers anthropics/claude-code#22620
- 7: [BUG] excludedCommands in sandbox settings doesn't bypass sandbox anthropics/claude-code#17821
- 8: [BUG] The setting excludedCommands doesn't seem to be respected. anthropics/claude-code#10524
- 9: sandbox.excludedCommands does not bypass network restrictions (SSH blocked for git) anthropics/claude-code#30619
- 10: excludedCommands glob matching unsandboxes entire shell invocation, enabling sandbox escape via command chaining anthropics/claude-code#40831
- 11: https://antisimplistic.com/posts/2026-02-02-claude-code-permissions/index.html
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Relevant line context:\n'
awk 'NR>=1 && NR<=110 { printf "%6d\t%s\n", NR, $0 }' docs/claude-code-sandbox.md
printf '\nSearch for sandbox/excludedCommands/dangerouslyDisableSandbox:\n'
rg -n "dangerouslyDisableSandbox|excludedCommands|sandbox|allowUnsandboxedCommands|Claude Code" docs .uloop Packages cli 2>/dev/null || trueRepository: hatayama/unity-cli-loop
Length of output: 7971
Warn that both remedies bypass sandbox protections.
Add a brief warning under Remedies: these options allow uloop execution outside the Claude Code sandbox, so only use trusted dev binaries and follow any organization policy for unsandboxed execution.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/claude-code-sandbox.md` around lines 60 - 63, Add a brief warning under
the Remedies section stating that both options bypass Claude Code sandbox
protections, and advise using only trusted uloop dev binaries while following
organizational policies for unsandboxed execution. Keep the existing remedy
instructions unchanged.
Blind review of #2015: the documented socket filename did not match createEndpointName (UnityCliLoop-<sha256[:16]>, not the project name), the symptom bullet implied server bind logs exist without ULOOP_DEBUG, and the remedies omitted the ULOOP_PROJECT_RUNNER_PATH route the invocation table itself measures as working. Also mark the suggested excludedCommands glob as unverified, add the Windows named-pipe open question, and fix five awkward English spots.
745d114
into
feature/cli-discoverability-integration
Why
On 2026-07-26 a full investigation chased a healthy Unity Editor as an IPC bug because a sandboxed agent shell denies Unix domain socket
connect()/bind()with EPERM, and the CLI reports that as a retryabledial unix ...: i/o timeout(the misreporting itself is tracked separately as round12 PR-7). The confusing part is that plainuloop ...commands kept working in other sandboxed sessions: a typical personal Claude Code settings entry excludes"uloop *"from sandboxing, and the exclusion matches the typed command text, not the binary that ends up doing the work. This repository's own validation rule (always run the builtdist/<platform>/uloop) produces exactly the command shape the exclusion does not match, so this checkout gets hit while game projects never notice.What
docs/claude-code-sandbox.md: symptom, cause, the verified invocation matrix (plain dispatcher / env-var prefix /ULOOP_PROJECT_RUNNER_PATHincl. a priorexport/dist/...direct / raw socket), and the two remedies.AGENTS.md(CLAUDE.mdis its symlink) so the doc is found before anyone re-investigates the Editor side.All matrix rows were measured in a live sandboxed session on 2026-07-26.
Verification
Docs-only change; no code paths affected. Repository CI does not fire on integration-branch PRs (
pull_request.branchesis[main, v3-beta]).