Tutorial Rot

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 --wait

Network 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 Ready state OR the tutorial doesn't tell me that I should expect to be able to do that. (will #2798 address this?)
• Setting a policy with a policy.yaml file for the sandbox created in the github-sandbox tutorial is straightforward.

Reproduction Steps

1. Run openshell sandbox create with OpenShell v0.0.111-v0.0.115.
2. Exit the sandbox
3. Run openshell sandbox list and observe the sandbox's Phase as Error.

1. Create the my-github provider as you are instructed to in the tutorial.
2. Run openshell sandbox create ... --provider my-github with OpenShell v0.0.110-v0.0.115.
3. In another terminal, run openshell policy get <sandbox> --base > policy.yaml
4. Strip the metadata header from policy.yaml
5. Run openshell policy set <sandbox> --policy policy.yaml (As I understand it, the unmodified base policy is supposed to round trip without issue).
6. 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

Logs

Start by reading docs/get-started/tutorials/first-network-policy.mdx and docs/get-started/tutorials/github-sandbox.mdx, then reproduce the reported exit and policy set failures with the listed OpenShell versions. Check issue #2798 for the sandbox-exit behavior. Done means the tutorials either describe the supported behavior accurately or provide working steps for leaving a sandbox Ready and applying the policy.yaml policy.