Security

Configure Corporate Certificate Authority Trust

View as Markdown

Configure a corporate Certificate Authority (CA) before onboarding when an enterprise proxy re-signs external TLS with a root that OpenShell does not provide. NemoClaw imports a bounded corporate CA chain without replacing the OpenShell trust bundle.

Provide the Corporate CA Explicitly

Point NemoClaw at a PEM bundle that contains your corporate root and any required intermediates.

$export NEMOCLAW_CORPORATE_CA_BUNDLE=/path/to/corporate-ca.pem
$nemoclaw onboard

The explicit variable fails onboarding when the file is missing, invalid, unsafe, or a merged operating-system trust store. Use nemoclaw <name> rebuild after adding or changing the CA for an existing sandbox.

Understand Image and Runtime Trust

NemoClaw validates the selected bundle and bakes it into the sandbox image as NEMOCLAW_CORPORATE_CA_B64. The managed Dockerfile decodes it to the root-owned, read-only file /usr/local/share/nemoclaw/corporate-ca.pem. It also installs each validated certificate as a separate operating-system trust anchor and refreshes the OS trust bundle. This lets the in-sandbox OpenShell proxy validate TLS when it opens the upstream connection to an HTTPS inference, MCP, or custom-policy endpoint signed by that CA.

When onboarding supplies a corporate CA, the Dockerfile sets NODE_EXTRA_CA_CERTS and CURL_CA_BUNDLE in each final-stage build step that accesses the npm registry. This includes registry-backed npm remediation and runtime dependency installation that cross a TLS-inspecting proxy. The build does not retain either variable in the image configuration.

When NemoClaw selects a corporate CA, it sets NEMOCLAW_MANAGED_IMAGE_RUNTIME_USER=root for the image build. The OpenClaw managed startup runtime creates /run/nemoclaw/managed-startup-ca-bundle.pem as root:root with mode 0444 before it starts agent commands as the sandbox user. The sandbox user can read the merged bundle but cannot modify or replace it. Sandboxes still using the staged legacy direct-start path create /tmp/nemoclaw-ca-bundle.pem with mode 0444 as the same sandbox identity that runs the entrypoint and agent, so that compatibility path is read-only by mode but is not a privilege boundary.

For sandbox child processes, NemoClaw also appends the corporate CA to the OpenShell client trust bundle instead of replacing it. It points SSL_CERT_FILE, CURL_CA_BUNDLE, REQUESTS_CA_BUNDLE, GIT_SSL_CAINFO, and NODE_EXTRA_CA_CERTS at the merged bundle so curl, Python, Git, and Node.js trust both roots.

Understand Automatic Source Selection

NemoClaw checks corporate CA sources in this order:

  1. NEMOCLAW_CORPORATE_CA_BUNDLE.
  2. REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, then SSL_CERT_FILE.
  3. Host administrator anchor directories.

Invalid conventional CA variables are skipped with a warning so an ambient host setting does not break onboarding that did not request the import. The default administrator anchor directories are /usr/local/share/ca-certificates/ on Debian or Ubuntu and /etc/pki/ca-trust/source/anchors/ on RHEL or Fedora. Set NEMOCLAW_CORPORATE_CA_ANCHOR_DIRS to a platform path-list when your administrator anchors live elsewhere. Set it to an empty value to disable host-store scanning.

NemoClaw does not import merged trust stores such as /etc/ssl/certs/ca-certificates.crt because they combine the corporate root with broad public operating-system trust. If no administrator anchor validates, NemoClaw can import validated standalone CA files directly under /etc/ssl/certs/ while excluding the merged bundle, symlink fan-out, and ordinary leaf certificates. A corporate root that exists only as a hand-edited entry in a merged trust store must be provided through NEMOCLAW_CORPORATE_CA_BUNDLE.

Verify the Selected Source

Check onboarding build output for the source and path that NemoClaw selected. A successful selection logs baking corporate proxy CA from ... without printing certificate contents.

If a conventional variable points at a missing or invalid file, onboarding logs that the source was skipped for corporate CA import. An administrator anchor directory that contains candidates but no valid CA logs a similar warning. If no selection message appears, no source passed validation.

Use a Custom Dockerfile

Managed NemoClaw Dockerfiles implement the corporate CA build contract automatically. A custom Dockerfile must declare ARG NEMOCLAW_CORPORATE_CA_B64, validate and decode it into /usr/local/share/nemoclaw/corporate-ca.pem, install each certificate as an individual OS trust anchor, and refresh the OS trust bundle. Decoding only the application bundle is insufficient for OpenShell-inspected HTTPS because the proxy verifies the upstream TLS connection itself. If its build needs network access behind the corporate proxy, establish build-time trust before the dependency operations that require TLS.

In the final image stage, an OpenClaw custom Dockerfile must declare exactly one build argument named NEMOCLAW_MANAGED_IMAGE_RUNTIME_USER with default sandbox. Dockerfile instruction keywords are case-insensitive, but the argument name must match exactly. Before the final entrypoint, the stage must set USER ${NEMOCLAW_MANAGED_IMAGE_RUNTIME_USER}. The final entrypoint must use the trusted exec form ENTRYPOINT ["/usr/local/bin/nemoclaw-start"]. NemoClaw selects root when it bakes the corporate CA so the entrypoint can create the root-owned merged bundle before it starts agent commands. Automatic fallback and host-store sources are a no-op unless the Dockerfile declares NEMOCLAW_CORPORATE_CA_B64 and meets this startup contract. The explicit NEMOCLAW_CORPORATE_CA_BUNDLE path fails onboarding if either condition is not met.

Review the Trust Boundary

Every imported source must be a regular, readable, non-symlink PEM file that is not group-writable or world-writable. The file must be non-empty, stay within the corporate-chain size and certificate-count limits, and contain only certificates that parse as X.509 CA certificates with basicConstraints CA:TRUE. NemoClaw rejects or skips a source that would widen trust to a full operating-system bundle instead of truncating it.

Set NEMOCLAW_CORPORATE_CA_IMPORT=0 to disable corporate CA import entirely.