From e9f55826994dbff0c3612453ead7a7cf42baf9d6 Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Tue, 19 May 2026 10:59:59 +0100 Subject: [PATCH 1/2] docs(reference): document openshell settings + sandbox runtime env MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #3718. Adds two sections to docs/reference/commands.md (and the .mdx mirror): - '## openshell settings' — get/set/delete usage, scope semantics, and the three named keys exposed on OpenShell 0.0.39 (agent_policy_proposals_enabled, ocsf_json_enabled, providers_v2_enabled). - '### Sandbox Runtime Environment' under the existing Environment Variables section — documents the fixed env vars NemoClaw stamps into every sandbox: OPENSHELL_SANDBOX, HOME, USER, HERMES_HOME, the host proxy at http://10.200.0.1:3128 (overridable via NEMOCLAW_PROXY_HOST / NEMOCLAW_PROXY_PORT), and the OpenShell-managed CA bundle pins (SSL_CERT_FILE, CURL_CA_BUNDLE, REQUESTS_CA_BUNDLE, GIT_SSL_CAINFO, NODE_EXTRA_CA_CERTS). Both gaps were reported in #3718: the openshell settings subcommand family was never mentioned, and operators debugging in-sandbox TLS or HTTP failures had no documented starting point for the proxy hop or the CA pin. Signed-off-by: Rohit Ghumare --- docs/reference/commands.mdx | 45 +++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 090df528f7e..a3e2ff957f6 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -898,6 +898,28 @@ $ openshell term For a remote Brev instance, SSH to the instance and run `openshell term` there, or use a port-forward to the gateway. +## `openshell settings` + +Manage sandbox and gateway settings exposed by OpenShell. NemoClaw does not wrap these; run them directly with the `openshell` CLI on the host where the sandbox lives. + +```console +$ openshell settings get [ | --global] +$ openshell settings set [ | --global] --key --value +$ openshell settings delete [ | --global] --key +``` + +`openshell settings get ` prints the effective settings for that sandbox plus the config revision and policy hash that produced them. `--global` reads or writes the gateway-wide scope; a sandbox-scoped value always overrides the global value when both are set. + +The current named settings on OpenShell 0.0.39 are: + +| Key | Type | Effect | +|-----|------|--------| +| `agent_policy_proposals_enabled` | boolean | When set, the agent loop is allowed to propose new network policy entries from inside the sandbox. The proposals still require operator approval through `openshell term` before they affect egress. | +| `ocsf_json_enabled` | boolean | When set, OpenShell emits sandbox audit events as OCSF JSON in addition to the human-readable log stream. Set this when feeding the audit log into a SIEM. | +| `providers_v2_enabled` | boolean | When set, the sandbox uses the v2 inference provider plane (the same plane NemoClaw's `nemoclaw inference set` writes to). Leave unset on releases older than v0.0.44. | + +Unset keys fall through to the gateway-global value, and an unset global value falls through to the OpenShell default for that key. + ### `nemoclaw tunnel start` Start optional host auxiliary services. This is the cloudflared tunnel when `cloudflared` is installed (for a public URL to the dashboard). Channel messaging (Telegram, Discord, Slack) is not started here; it is configured during `nemoclaw onboard` and runs through OpenShell-managed constructs. @@ -1236,6 +1258,29 @@ These flags change defaults for commands that manage existing sandboxes. | `NEMOCLAW_CLEANUP_GATEWAY` | `1`, `true`, or `yes` to enable; `0`, `false`, or `no` to disable | Sets the default for whether `nemoclaw destroy` removes the shared gateway when destroying the last sandbox. Command-line `--cleanup-gateway` and `--no-cleanup-gateway` still take precedence. | | `NEMOCLAW_DISABLE_INFERENCE_ROUTE_REPAIR` | `1` to enable | Skips the automatic DNS-proxy repair for stale `inference.local` routes during `nemoclaw connect` and `nemoclaw connect --probe-only`. Use only as a troubleshooting escape hatch. | +### Sandbox Runtime Environment + +The variables above run on the host. NemoClaw also stamps a fixed set of environment variables *inside* every sandbox it creates. They are not configured by the operator; they document the runtime the agent process sees. Operators debugging in-sandbox network or TLS failures start here. + +Read the live values for any sandbox with `openshell sandbox exec -n -- env | sort`. + +| Variable | Value | Effect | +|----------|-------|--------| +| `OPENSHELL_SANDBOX` | `1` | Set inside the sandbox only. Use in scripts that need to detect whether they are running inside an OpenShell sandbox. | +| `HOME` | `/sandbox` | Sandbox process home. NemoClaw-provisioned config lives under `/sandbox/.openclaw` (OpenClaw) and `/sandbox/.hermes` (Hermes). | +| `USER` | `sandbox` | Sandbox process identity. | +| `HERMES_HOME` | `/sandbox/.hermes` | Hermes config root. Present in Hermes sandboxes only. | +| `http_proxy`, `https_proxy`, `grpc_proxy`, `ALL_PROXY` (and the upper-case `HTTP_PROXY` / `HTTPS_PROXY` variants) | `http://10.200.0.1:3128` | Every outbound HTTP, HTTPS, and gRPC call from the sandbox is forced through this host-side OpenShell proxy. The sandbox cannot reach the outside world directly; egress is gateway-mediated and subject to the active network policy. Override the host and port with the `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` host variables at onboard time. | +| `NO_PROXY` | `localhost,127.0.0.1,::1,10.200.0.1` | Loopback and the proxy itself bypass the proxy. | +| `NODE_USE_ENV_PROXY` | `1` | Tells Node.js (22+) to honor the proxy env vars above so in-sandbox `node` and `npm` traffic is also gateway-mediated. | +| `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `REQUESTS_CA_BUNDLE`, `GIT_SSL_CAINFO` | `/etc/openshell-tls/ca-bundle.pem` | Pins `curl`, `python-requests`, and `git` to the OpenShell-managed CA bundle. | +| `NODE_EXTRA_CA_CERTS` | `/etc/openshell-tls/openshell-ca.pem` | Pins Node.js TLS verification to the OpenShell-managed CA. | + +The proxy IP, port, and CA bundle paths are the source of two common in-sandbox failures: + +- TLS errors from `curl`, `python-requests`, `git`, or `node` usually mean the CA bundle has been overridden or the binary is not honoring the env vars above. Check `cat /etc/openshell-tls/ca-bundle.pem` from inside the sandbox and confirm the binary in question reads `SSL_CERT_FILE` (or its equivalent). +- Timeouts on outbound HTTP usually mean the destination is not in the active policy. Use `openshell policy get` on the host to see what is currently allowed, and `nemoclaw policy-add` to add a preset. + ## NemoHermes Alias `nemohermes` is a convenience alias that pre-selects the Hermes agent. From 414ab1e9de5e4862acb0cb6683a3af45f371dfec Mon Sep 17 00:00:00 2001 From: Rohit Ghumare Date: Tue, 19 May 2026 12:57:31 +0100 Subject: [PATCH 2/2] docs(reference): one sentence per line in new sections Applies docs/CONTRIBUTING.md:230 (one sentence per line) to the prose added in the openshell settings + sandbox runtime env sections from the previous commit. No wording, anchor, or table changes. Signed-off-by: Rohit Ghumare --- docs/reference/commands.mdx | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index a3e2ff957f6..3856ed1f4aa 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -900,7 +900,8 @@ For a remote Brev instance, SSH to the instance and run `openshell term` there, ## `openshell settings` -Manage sandbox and gateway settings exposed by OpenShell. NemoClaw does not wrap these; run them directly with the `openshell` CLI on the host where the sandbox lives. +Manage sandbox and gateway settings exposed by OpenShell. +NemoClaw does not wrap these; run them directly with the `openshell` CLI on the host where the sandbox lives. ```console $ openshell settings get [ | --global] @@ -908,7 +909,9 @@ $ openshell settings set [ | --global] --key --value $ openshell settings delete [ | --global] --key ``` -`openshell settings get ` prints the effective settings for that sandbox plus the config revision and policy hash that produced them. `--global` reads or writes the gateway-wide scope; a sandbox-scoped value always overrides the global value when both are set. +`openshell settings get ` prints the effective settings for that sandbox plus the config revision and policy hash that produced them. +`--global` reads or writes the gateway-wide scope. +A sandbox-scoped value always overrides the global value when both are set. The current named settings on OpenShell 0.0.39 are: @@ -1260,7 +1263,10 @@ These flags change defaults for commands that manage existing sandboxes. ### Sandbox Runtime Environment -The variables above run on the host. NemoClaw also stamps a fixed set of environment variables *inside* every sandbox it creates. They are not configured by the operator; they document the runtime the agent process sees. Operators debugging in-sandbox network or TLS failures start here. +The variables above run on the host. +NemoClaw also stamps a fixed set of environment variables *inside* every sandbox it creates. +They are not configured by the operator; they document the runtime the agent process sees. +Operators debugging in-sandbox network or TLS failures start here. Read the live values for any sandbox with `openshell sandbox exec -n -- env | sort`. @@ -1278,8 +1284,10 @@ Read the live values for any sandbox with `openshell sandbox exec -n -- e The proxy IP, port, and CA bundle paths are the source of two common in-sandbox failures: -- TLS errors from `curl`, `python-requests`, `git`, or `node` usually mean the CA bundle has been overridden or the binary is not honoring the env vars above. Check `cat /etc/openshell-tls/ca-bundle.pem` from inside the sandbox and confirm the binary in question reads `SSL_CERT_FILE` (or its equivalent). -- Timeouts on outbound HTTP usually mean the destination is not in the active policy. Use `openshell policy get` on the host to see what is currently allowed, and `nemoclaw policy-add` to add a preset. +- TLS errors from `curl`, `python-requests`, `git`, or `node` usually mean the CA bundle has been overridden or the binary is not honoring the env vars above. + Check `cat /etc/openshell-tls/ca-bundle.pem` from inside the sandbox and confirm the binary in question reads `SSL_CERT_FILE` (or its equivalent). +- Timeouts on outbound HTTP usually mean the destination is not in the active policy. + Use `openshell policy get` on the host to see what is currently allowed, and `nemoclaw policy-add` to add a preset. ## NemoHermes Alias