Repository navigation
Tutorial Rot #2998
Description
User Story
As a new user, I want to follow the tutorials on the documentation website, so I can learn how to use OpenShell.
Problem Statement
The first-network-policy tutorial states:
Exit the sandbox. Sandboxes are kept running by default, so you can reconnect later. Use --no-keep at creation time if you want the sandbox deleted after exit
However, when exiting a sandbox, it enters into an Error state, and can not be reconnected to.
The github-sandbox tutorial states
After you have reviewed the generated policy, apply it to the running sandbox:
openshell policy set <sandbox-name> --policy /tmp/sandbox-policy-update.yaml --waitNetwork policies are hot-reloadable. The --wait flag blocks until the policy engine confirms the new revision loaded, and the update takes effect immediately without restarting the sandbox or reconnecting Claude Code.
However, openshell policy set has been nearly impossible to get working on a running sandbox.
Impact / Why This Matters
When this happens, users must begin looking outside the tutorial for solutions to these problems, e.g. by reading other parts of the documentation, asking LLMs, and messing with the CLI. This costs lots of time and has no guarantee that they will find a proper workaround, potentially leading to them abandoning the tool or working with a broken setup.
Acceptance Criteria
- The tutorial tells me how to exit a sandbox leaving it in a
Readystate OR the tutorial doesn't tell me that I should expect to be able to do that. (will feat(sandbox): add main restart policy #2798 address this?) - Setting a policy with a
policy.yamlfile for the sandbox created in thegithub-sandboxtutorial is straightforward.
Reproduction Steps
- Run
openshell sandbox createwith OpenShell v0.0.111-v0.0.115. - Exit the sandbox
- Run
openshell sandbox listand observe the sandbox'sPhaseasError.
- Create the
my-githubprovider as you are instructed to in the tutorial. - Run
openshell sandbox create ... --provider my-githubwith OpenShell v0.0.110-v0.0.115. - In another terminal, run
openshell policy get <sandbox> --base > policy.yaml - Strip the metadata header from
policy.yaml - Run
openshell policy set <sandbox> --policy policy.yaml(As I understand it, the unmodified base policy is supposed to round trip without issue). - Observe an error similar to this:
Error: × code: 'The system is not in a state required for the operation's execution', message: "credentialed endpoint 'github.com:443' in rule 'pypi' uses L4-only; configure L7 inspection or explicitly set
│ allow_uninspected_credentials: true"
Environment
- OpenShell:
>=v0.0.111(or>=v0.0.110, for the policy issue). - OS: Ubuntu 25.04
- Runtime: Podman v5.4.1
Activity
elezar commentedon Aug 28, 2026
fbricon commentedon Aug 31, 2026
We're directly affected by the "allow_uninspected_credentials" error.
What our Kaiden project does, is akin to:
openshell sandbox create --name my-sandbox --provider my-github(tested with OpenShell v0.0.113-v0.0.116).openshell policy update my-sandbox --add-endpoint registry.npmjs.org:443:full:rest --binary "/**"openshell chokes on a rule that already existed before adding something entirely unrelated
So this looks like a real bug, beyond just documentation rot.
fix(server): gate only newly authored uninspected credentialed endpoints
russellb commentedon Sep 2, 2026
Thanks for the detailed report — both problems are real and fixes are up for review.
allow_uninspected_credentialserror onpolicy set/update: With a GitHub provider attached, the gateway treats every rule reachinggithub.com/api.github.comas credentialed and rejects uninspected (L4) entries. The default policy and thegithub-sandboxtutorial listed those hosts as plain L4 endpoints in thepypi/copilotblocks, so any policy change failed — even an unrelated one. Fixes:Exit →
Error, can't reconnect: Exiting the interactive shell stops the sandbox's main process, which isn't reconnectable under the default restart policy. #3140 rewrites thefirst-network-policytutorial to keep the sandbox running via a second terminal; the underlying behavior is tracked in #2798.johntmyers commentedon Sep 2, 2026
@russellb I think this is caused by the fact that we have a very old base policy that isn't quite relevant to the state of the platform now. See: #3116. We'd like to move in a direction where orgs create their own base images and maintain them, to include their own default policies. We could perhaps have some fully-qualified polices and providers we keep around as examples. If we remove the base community images and provide getting started examples I'm wondering if we need any of these PRs to include #3129
fix(server): key inherited credential findings per port and revalidat…
docs: fix first-network-policy sandbox lifecycle flow
russellb commentedon Sep 2, 2026
@johntmyers Agreed — #3129 is the right fix. Making the gate differential (so inherited endpoints from the baked policy don't block unrelated edits) addresses the second acceptance criterion far better than patching the policy, and with #3116 retiring the community base image and its policy, patching that policy isn't worth it. So:
first-network-policytutorial fix and dropped the credential/default-policy doc changes, since those overlap fix(server): gate only newly authored uninspected credentialed endpoints #3129 and will be reworked by refactor(sandbox)!: retire community images and default to Alpine #3116.The remaining bit in #3140 is unrelated to the credential gate: the tutorial tells users to exit and reconnect, but exiting the interactive shell leaves the sandbox unreconnectable — a lifecycle issue tied to #2798, not #3116/#3129. Happy to hold even that if you'd rather fold the tutorial rewrites into the #3116 work.
docs: fix first-network-policy sandbox lifecycle flow (NVIDIA#3140)