Skip to main content
OpenCode takes its whole configuration as a JSON string in an environment variable, which suits a disposable box: nothing to mount, nothing left behind, and the provider block can be assembled by your orchestration code.

Prerequisites

  • The boxlite Python package and a machine with hardware virtualization — see Installation.
  • An API key for a provider OpenCode supports.
  • A Node image for the box. OpenCode installs from npm, so node:20-slim or newer works.

Quick Example

Install the CLI, inject a provider through OPENCODE_CONFIG_CONTENT, and run one prompt.
Verified output shape from a real run of the same command — OpenCode prints the agent and model it selected, then the answer:
Seeing the > build · <model> line is the signal that the provider block was accepted. If the model does not resolve, you get an error instead of that line. Verified inside a box on macOS (Apple Silicon): the global npm install took about 20 s and the prompt returned 6 s later. An 8 GB disk came back 9% used.

Parameters and Returns

From opencode --help and opencode run --help: Configuration environment variables: OPENCODE_CONFIG_CONTENT (whole config as JSON), OPENCODE_CONFIG (path to a config file), OPENCODE_CONFIG_DIR.

Keeping the API key out of the box

OPENCODE_CONFIG_CONTENT keeps the key out of any file, but it is still an environment variable inside the sandbox. To keep the real value on the host entirely, put a placeholder in the config and let the proxy substitute it on the way out:
The placeholder goes where the key would have gone in the config JSON. Substitution covers request headers, the URL query string, and the request body — not the URL path. See Secrets and hardening for the placeholder format.

Long-running use: opencode serve

For more than one prompt, run the headless server and forward its port instead of paying the install and start cost per call:
Port forwarding requires the service to bind 0.0.0.0 rather than 127.0.0.1 — see Network access.

Troubleshooting

  • Run Pi — configures custom endpoints through a config file instead of an environment variable.
  • Run Codex — configures its endpoint through environment variables.
  • Network access — forwarding opencode serve to the host.