Prerequisites
- The
boxlitePython 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-slimor newer works.
Quick Example
Install the CLI, inject a provider throughOPENCODE_CONFIG_CONTENT, and run one prompt.
> 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
Fromopencode --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:
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:
0.0.0.0 rather than 127.0.0.1 — see Network access.
Troubleshooting
Related
- 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 serveto the host.

