docs: add internal CA sandbox troubleshooting

[dvdksn]

Summary

Add troubleshooting guidance for Docker Sandboxes users whose internal HTTPS inspection proxy requires a custom CA certificate inside the sandbox. The section covers repeatable setup with a sandbox kit, one-off setup for existing sandboxes, Node.js CA configuration, and policy log diagnostics.

Generated by Codex

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	e95dcaf
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a213db793f8110008dd32c6
😎 Deploy Preview	https://deploy-preview-25198--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[docker-agent]

Assessment: 🟢 APPROVE

The new "API calls fail with a certificate error" troubleshooting section is well-structured and technically clear. Commands use correct console language hints, YAML blocks are properly formatted, and the instructions are actionable and accurate.

No hedge words, bold misuse, marketing language, missing front matter, or broken shortcodes were found. The addition matches the existing document's scope and character.

[docker-agent]

Assessment: 🟢 APPROVE

The added troubleshooting guidance for internal CA certificates is well-written and accurate. Both new sections follow Docker's documentation style guide: no AI-isms, correct command formatting, appropriate bold usage consistent with existing patterns, and accurate technical content (the kit file path mapping is correct). The content is appropriately scoped and no redirects are needed (new sections added to existing pages only).

[docker-agent]

Assessment: 🔴 CRITICAL

One high-severity issue found in the added content: a dangling cross-reference to NODE_EXTRA_CA_CERTS in the kit example.

[byjrack]

Sorry on the lag in review.

So we have 3 egress paths; forward, forward-bypass, and transparent.

In transparent I believe we would see the MITM proxy (their perimeter) TLS trust make it to any HTTP stack in the sandbox. For forward-bypass will the server hello be from our proxy or theirs?

So i would think we would focus this doc around detecting the specific issue so the fix can be be more precise. Makes me wonder if the transparent vs forward-bypass is going to create more ambiguity. If we can get all TLS to our proxy than our internal CA can mask their MITM CA.

Another thing i am thinking about is we need to stress with folks not to override internal env vars with their MITM. If they change the SSL_CERT_FILE etc to enable their injected cert list it will break ours when in forward.

[dvdksn]

Thanks @byjrack — really helpful.

On your last point: added an [!IMPORTANT] callout in 4924fc6 warning users not to override the sandbox's TLS trust env vars (SSL_CERT_FILE etc.) to point only at their internal CA, since that replaces the system bundle and breaks the credential proxy's trust on the forward path. Install into the system trust store instead.

On the egress-path framing — I'd like to make the detection guidance precise rather than ambiguous, but I want to confirm the behavior first:

• transparent: sandbox sees the customer's perimeter MITM cert, so installing their internal CA is the right fix. ✅
• forward: our proxy terminates TLS and presents our CA, so the sandbox should already trust it — no internal-CA install needed (and overriding env vars would break it, hence the callout).
• forward-bypass: this is the one I'm unsure about — is the server hello from our proxy or theirs? That determines whether the internal-CA install applies here too.

Once you confirm the forward-bypass behavior, I'll reframe the section around "identify your egress path, then apply the matching fix" so it's unambiguous. Does that split sound right to you?

_{Generated by Claude Code}

[robmry]

Makes me wonder if the transparent vs forward-bypass is going to create more ambiguity. If we can get all TLS to our proxy than our internal CA can mask their MITM CA.

When there's no upstream proxy MITM-ing - If we MITM when secrets injection isn't needed, we'll break network access for containers running inside the sandbox (because they won't normally have the sandbox's CA cert installed).

When there is an upstream proxy - yes, perhaps the user would want us to MITM everything so they don't need to install their proxy's cert in the sandbox. We could look at that if folks have trouble installing the cert (we could also make it easier to install the cert).

• transparent: sandbox sees the customer's perimeter MITM cert, so installing their internal CA is the right fix.
• forward: our proxy terminates TLS and presents our CA, so the sandbox should already trust it — no internal-CA install needed (and overriding env vars would break it, hence the callout).
• forward-bypass: this is the one I'm unsure about — is the server hello from our proxy or theirs? That determines whether the internal-CA install applies here too.

Transparent and forward-bypass are equivalent - we just forward packets. The only difference is whether the client knows it's talking to a proxy.