From a4b7dac680e0297c221213be1bf50c1c510e07fd Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 24 Jul 2026 15:46:06 +0000
Subject: [PATCH] docs: document OpenCode Zen sandbox key setup

---
 .../manuals/ai/sandboxes/agents/opencode.md   | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/content/manuals/ai/sandboxes/agents/opencode.md b/content/manuals/ai/sandboxes/agents/opencode.md
index cefad09337b5..d5bc06679dd5 100644
--- a/content/manuals/ai/sandboxes/agents/opencode.md
+++ b/content/manuals/ai/sandboxes/agents/opencode.md
@@ -48,6 +48,34 @@ $ sbx secret set -g openrouter
 You only need to configure the providers you want to use. OpenCode detects
 available credentials and offers those providers in the TUI.
 
+### OpenCode Zen API keys
+
+OpenCode Zen API keys aren't part of the built-in OpenCode credentials that
+`sbx secret set` supports. To use an OpenCode Zen API key, store it as a
+[custom secret](../security/credentials.md#custom-secrets):
+
+Set the `OPENCODE_API_KEY` environment variable on the host, then store it:
+
+```console
+$ sbx secret set-custom -g \
+    --host opencode.ai \
+    --env OPENCODE_API_KEY \
+    --value "$OPENCODE_API_KEY"
+```
+
+Custom secrets keep the real key in the host secret store. The sandbox receives
+`OPENCODE_API_KEY` as a placeholder, and the host-side proxy replaces that
+placeholder with the real key on requests to `opencode.ai`.
+
+OpenCode Zen also requires network access to `opencode.ai`:
+
+```console
+$ sbx policy allow network opencode.ai:443
+```
+
+If you add the custom secret globally with `-g`, recreate existing OpenCode
+sandboxes so the new environment variable is available inside the sandbox.
+
 ## Configuration
 
 Sandboxes don't pick up user-level configuration from your host. Only