PROD-250 docs: sandbox OpenShell microVM provider (additional) - #162
Closed
salamisandwich77 wants to merge 11 commits into
Closed
PROD-250 docs: sandbox OpenShell microVM provider (additional)#162salamisandwich77 wants to merge 11 commits into
salamisandwich77 wants to merge 11 commits into
Conversation
Adds the OpenShell provider page on top of the base sandbox section: the supported platforms and their published assets, the prepared VM cache, the OCI registry mode for development, registry CA trust on each platform, and the security properties and limitations. Restores the sidebar entry and the four cross-references from the native provider, provisioning, configuration, and sandbox-execution pages. The page states what this provider costs relative to the default: it needs a prepared image cache and a hypervisor, and OpenBox publishes a complete asset set only for Apple Silicon macOS and x86_64 glibc Linux.
configuration.md conflicted: the base corrected the provision command and this branch added the OpenShell cross-reference. Both are kept.
The flag did nothing and has now been removed from the launcher, so a command carrying it fails rather than being ignored. The page also described it as accepting defaults and not bypassing the KVM, signing, and CA-trust checks; provisioning never prompts, and those checks stand on their own.
Four things stopped the page working as written. The published SDK installs without error and does not contain `openbox.sandbox`, so the example died at an import in step 4 with nothing on the page explaining it. Step 3 now states that plainly and gives the editable install that does work. `temporal server start-dev` was a clause inside a sentence about other requirements. It is a hard prerequisite for step 4, so it is a command block of its own. `uv init` writes a `main.py` that `uv run python .` ignores, which is confusing next to an example made of two other files. The page says to remove it. Troubleshooting named an error the example cannot produce: it reads the boundary values from the environment directly, so a missing one raises `KeyError`, not the SDK's message. That entry is corrected, and entries for the missing module and for a port still held by an earlier service are added.
The page carried a caution that the published SDK lacks openbox.sandbox and told the reader to install from a local checkout. The sandbox work is treated as merged, so the documented install is the plain one.
Configuration listed seven environment variables and said parameters override them. The package reads the process environment once, in sandbox/deployment.py, and that read has nothing to do with plugin configuration. Setting OPENBOX_GOVERNANCE_TIMEOUT, OPENBOX_ENABLED, OPENBOX_GOVERNANCE_POLICY, OPENBOX_SEND_START_EVENT or OPENBOX_SEND_ACTIVITY_START_EVENT changed nothing. The plugin takes constructor parameters. OPENBOX_URL and OPENBOX_API_KEY are conventional names that your own code reads and passes in, which is why the example does exactly that. The walkthrough's .env carried four of the inert variables, including OPENBOX_GOVERNANCE_MAX_RETRIES, which is not a parameter either. Also relabels a constructor signature in the SDK reference as text, since it is an illustration rather than code that parses.
Saying the variables have no effect answered half the question. The SDK's own README documents OPENBOX_GOVERNANCE_TIMEOUT and OPENBOX_GOVERNANCE_POLICY as names an application reads and passes in, the same way the examples already treat OPENBOX_URL and OPENBOX_API_KEY. The page now shows that pattern.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Author
|
Reopened on a fresh branch (docs/sandbox-openshell-provider-v2) so the stack tool sees one PR per branch. The old branch stays in merged PR #160. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
OpenShell Provider (VM)
Documentation for the optional microVM sandbox provider.
openshellruns the admitted command inside a libkrun microVM, giving a guest-kernel boundary rather than the host-kernel isolation the defaultnativeprovider applies. It uses Hypervisor.framework on macOS and KVM on Linux.The page covers supported platforms and the assets published for each, the prepared VM cache that keeps warm-up to a cache hit, the OCI registry mode for development, registry CA trust per platform, and the security properties and limits.
Provider selection is explicit and fails closed; there is no fallback to
native.Stacked on #157. The base sandbox section must land first, since this page links to Provisioning, Native Provider, and Concept.
Replaces #160. That pull request was closed as merged on 2026-08-26 by an accidental
git pullthat pulled this branch into its own base branch. The merge commit was reverted, so none of this work reached the base branch. GitHub cannot reopen a pull request once it records it as merged, so this is a new one against the same base with the same branch.