docs: refresh user-facing docs for recent sandbox and inference changes#868
Open
docs: refresh user-facing docs for recent sandbox and inference changes#868
Conversation
- architecture: document system CA loading for upstream TLS, `tls: skip` as the opt-out, gateway state persistence across restarts, and OCSF structured logging surface. - inference: document per-provider header allowlist, Authorization stripping, 120s streaming idle tolerance, and extended-thinking timeout guidance. - manage-sandboxes: add "Execute a Command in a Sandbox" section for `openshell sandbox exec` with flag reference. - security best practices: expand seccomp denylist (unconditional and conditional blocks), document two-phase Landlock probe, High-severity `landlock-unavailable` finding, and inference keep-alive closure. - observability logging: document port in HTTP log URLs, `[reason:...]` denial suffixes, proxy 403/502 JSON error bodies, and Landlock CONFIG:ENABLED/CONFIG:OTHER events. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
|
🌿 Preview your docs: https://nvidia-preview-pr-868.docs.buildwithfern.com/openshell |
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
Trim implementation detail (CA bundle paths, deprecated TLS keys, SSH handshake secret) from the high-level architecture page, fix accuracy issues surfaced during deep audit, and expand uncommon acronyms on first mention. - Drop unsupported "cost-based routing" claim from Privacy Router row. - Replace "brokers requests across the platform" with auth-boundary description. - Add "inference" to Policy Engine constraint list per AGENTS.md. - Expand Deny rule to include SSRF, blocked control-plane port, and L7 deny paths in addition to deny-by-default. - Switch Allow/Deny labels from hyphen to colon; remove em dashes and a double space. - Expand LLM, SSRF, L7, TLS, CA, PEM, SSH, OCSF, and JSONL on first use. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com> Made-with: Cursor
- observability/logging: rewrite the allowed_ips paragraph after the Denial Reasons table; the previous wording said authors "can use" invalid entries while also stating they were rejected, which was contradictory and conflated load-time validation with the runtime per-CONNECT denial phrases the section documents. - about/architecture: split compound sentences in the new Gateway Lifecycle and Observability sections so each clause stands alone. - inference/about: drop the streaming-tolerance sentence from the prose paragraph since the dedicated Streaming reliability table row already covers it. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com> Made-with: Cursor
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.
Summary
Catches up the published docs to the last ~4 weeks of user-facing changes across sandbox, inference routing, CLI, and observability. Scanned 87 commits since 2026-03-23, mapped user-facing commits to doc pages, and verified each edit against the code rather than commit messages alone.
Related Issue
Changes
docs/about/architecture.mdx3b21df1).tls: skipdocumented as the opt-out, deprecatingtls: terminate/tls: passthrough(feat(sandbox): auto-detect TLS and terminate unconditionally for credential injection #544,f37b69b).gateway stop/gateway start(fix(bootstrap,server): persist sandbox state across gateway stop/start cycles #739,491c5d8).e837849).b7779bd).inferenceto Policy Engine constraint list, and expanded LLM / SSRF / L7 / TLS / CA / PEM / SSH / OCSF / JSONL on first use (db243e5).docs/inference/about.mdx25d2530):openai-organization,x-model-id.anthropic-version,anthropic-beta.x-model-id.Authorizationstripped before forwarding (fix(inference): allowlist routed request headers #826,25d2530).355d845).docs/inference/configure.mdx/inference/about(fix(inference): allowlist routed request headers #826,25d2530).--timeoutdocs (feat(inference): allow setting custom inference timeout #672,36329a1; fix(inference): prevent silent truncation of large streaming responses #834,355d845).docs/sandboxes/manage-sandboxes.mdxopenshell sandbox exec(feat(cli): add sandbox exec subcommand with TTY support #752,13262e1):-n,--workdir,--timeout,--tty,--no-tty.docs/security/best-practices.mdx8887d7c):mount,pivot_root,ptrace,bpf,pidfd_*,io_uring_setup,perf_event_open, etc.execveatwithAT_EMPTY_PATH,unshare/clonewithCLONE_NEWUSER,seccomp(SECCOMP_SET_MODE_FILTER).28db08e).landlock-unavailableOCSF finding (fix(sandbox): two-phase Landlock to fix privilege ordering and add enforcement tests #810,29a3b1c).1cabd25).docs/observability/logging.mdx09af1b6).[reason:...]denial suffix table with real reason phrases (bug: link-local / loopback entries in allowed_ips are silently accepted but never enforced #814,2ca553a).CONFIG:ENABLEDstartup events (ABI, ro/rw counts) and[MED]CONFIG:OTHERper-path skip event (fix(sandbox): emit warning when Landlock filesystem sandbox degrades silently #599,6828e14).Testing
mise run docspasses (0 errors, 2 pre-existing warnings unrelated to these changes: upstream FDR 500 and a theme contrast-ratio check).mise run pre-commit— rust:lint fails locally on az3.hnot-found build-env issue unrelated to doc changes; CI will run the full check.Checklist
docs:).docs/about/architecture.mdx, which is included above).