From 2e69cb0506e8bf15ea7e681c6392332ef329a31c Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 28 May 2026 14:01:43 +0200 Subject: [PATCH 1/2] docs: add internal CA sandbox troubleshooting Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- .../manuals/ai/sandboxes/troubleshooting.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 0430031207d..b9e80795a7f 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -109,6 +109,72 @@ configured to use the forward proxy. See [Monitoring network activity](security/policy.md#monitoring) for details. +## API calls fail with a certificate error + +If your organization uses a proxy that inspects HTTPS traffic, agent requests +can fail with a certificate error such as +`SSL certificate problem: self-signed certificate in certificate chain`. Install +your organization's internal root CA inside the sandbox so the agent and its +SDKs trust certificates signed by the proxy. Certificate errors can stop a +request before the credential proxy can inject credentials. + +For repeatable setup, create a [sandbox kit](customize/kits.md) that installs +the CA when the sandbox is created: + +```text +internal-ca/ +|-- spec.yaml +`-- files/ + `-- home/ + `-- internal-ca.crt +``` + +Use a PEM-encoded certificate with a `.crt` extension. If traffic can be signed +by more than one internal proxy, include each proxy's root CA in the kit and +install each certificate before running `update-ca-certificates`. + +Add this `spec.yaml`: + +```yaml {title="internal-ca/spec.yaml"} +schemaVersion: "1" +kind: mixin +name: internal-ca + +environment: + variables: + NODE_EXTRA_CA_CERTS: /usr/local/share/ca-certificates/internal-ca.crt + +commands: + install: + - command: "install -m 0644 /home/agent/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt && update-ca-certificates" + user: "0" + description: Install internal CA certificate +``` + +Create a sandbox with the kit: + +```console +$ sbx run claude --kit ./internal-ca/ +``` + +To update an existing sandbox, copy the certificate into the sandbox and update +the trust store: + +```console +$ sbx cp ./internal-ca.crt :/tmp/internal-ca.crt +$ sbx exec -- sudo install -m 0644 /tmp/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt +$ sbx exec -- sudo update-ca-certificates +``` + +Some Node.js-based agents and SDKs use their own certificate store. Set +`NODE_EXTRA_CA_CERTS` inside the sandbox, as shown in the kit example, so those +clients also trust the internal CA. + +If API calls still fail after installing the CA, run `sbx policy log` and check +whether the request used `forward`, `forward-bypass`, or `transparent` in the +**PROXY** column. That can help identify whether the request is eligible for +credential injection or is reaching an upstream proxy directly. + ## Docker build export fails with an ownership error Running `docker build` with the local exporter (`--output=type=local` or `-o From d5c2dd6395bb4d546aec240ea37674ae563336b8 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 28 May 2026 15:01:39 +0200 Subject: [PATCH 2/2] docs: move internal CA kit example --- .../ai/sandboxes/customize/kit-examples.md | 38 +++++++++++++++++++ .../manuals/ai/sandboxes/troubleshooting.md | 34 +++-------------- 2 files changed, 43 insertions(+), 29 deletions(-) diff --git a/content/manuals/ai/sandboxes/customize/kit-examples.md b/content/manuals/ai/sandboxes/customize/kit-examples.md index 1027ea8f4b5..c928f313202 100644 --- a/content/manuals/ai/sandboxes/customize/kit-examples.md +++ b/content/manuals/ai/sandboxes/customize/kit-examples.md @@ -72,6 +72,44 @@ step should run as the agent user — for example, `npm install -g` against a user-scoped prefix, or anything that writes to `/home/agent/`. +## Install an internal CA certificate + +If your organization uses a proxy that inspects HTTPS traffic, install +the proxy's internal root CA in the sandbox trust store. This helps +agents and SDKs trust certificates signed by the proxy. + +```text +internal-ca/ +├── spec.yaml +└── files/ + └── home/ + └── internal-ca.crt +``` + +Use a PEM-encoded certificate with a `.crt` extension. If traffic can +be signed by more than one internal proxy, include each proxy's root +CA in the kit and install each certificate before running +`update-ca-certificates`. + +```yaml {title="internal-ca/spec.yaml"} +schemaVersion: "1" +kind: mixin +name: internal-ca + +environment: + variables: + NODE_EXTRA_CA_CERTS: /usr/local/share/ca-certificates/internal-ca.crt + +commands: + install: + - command: "install -m 0644 /home/agent/internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt && update-ca-certificates" + user: "0" + description: Install internal CA certificate +``` + +`NODE_EXTRA_CA_CERTS` helps Node.js-based agents and SDKs use the same +internal CA as the system trust store. + ## Run a background service