docs: document required sbx default network policy

[jasonkneen]

Problem

Installing via the curl one-liner works, but the first run fails to start the sandbox with no useful error — it appears to hang or fail silently.

Root cause: sbx refuses to create any sandbox until a default network policy is configured:

ERROR: default network policy has not been configured
Set a policy with: sbx policy set-default <allow-all|balanced|deny-all>

The README and install.sh only tell users to run sbx login — never sbx policy set-default. Because Fractal's sbx backend captures sbx create with capture_output=True and discards stderr, the real error never reaches the user; it surfaces as a silent sandbox-startup failure.

Reproduced and confirmed: after sbx policy set-default balanced, sbx create succeeds and fractal runs end-to-end.

Changes

• README.md: add sbx policy set-default balanced to the sbx prerequisite, explain the failure mode, and note the first-run sandbox image pull can take several minutes (with a pre-pull workaround).
• install.sh: include the policy step in the check_prereqs sbx hints.

Docs only — no behavior change.

Follow-up (not in this PR)

The sbx backend (predict_rlm/backends/sbx/backend.py) raises Failed to create sbx sandbox: <CalledProcessError> but discards the captured stderr. Surfacing exc.stderr would turn this from a silent failure into an obvious one. That lives in the vendored predict-rlm dependency, so it belongs upstream.

https://claude.ai/code/session_01CeJ5biNVPBwmnpFMv9Zjaf

[Copilot]

Pull request overview

Updates Fractal’s onboarding docs to prevent a first-run “silent” sandbox startup failure by documenting that sbx requires a default network policy before it can create sandboxes.

Changes:

• Add sbx policy set-default balanced to the README’s sbx prerequisites and describe the associated failure mode.
• Note that the first sandbox image pull can take several minutes and provide an optional pre-pull (“warm”) command.
• Update install.sh prerequisite hints to include the default network policy step.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
README.md	Documents the required sbx default network policy and first-run image pull behavior to avoid confusing startup failures.
install.sh	Extends prerequisite guidance to include setting the sbx default network policy alongside sbx login.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.