OpenCode in Docker with a paid model through OpenRouter

Introduction

This article is part of a larger manual, OpenCode in Docker on Ubuntu 24.04.

The manual shows how to run OpenCode with the --auto option inside a Docker container.

With --auto the agent does not ask you before each command, so the container limits what it can reach: the agent works only in one git worktree, a separate copy of the project.

This article shows how to give the container a paid model through OpenRouter.

The free OpenCode model has a usage limit (the free model has a usage limit).

An OpenRouter account gives the container paid models through one key.

The launcher reads the key from a file on the host and passes it to one run at a time; a run without it keeps the free model and gets no key.

1. A key for the container

Create a key of its own on the OpenRouter keys page (create an API key) and give it a credit limit (keys, limits and privacy).

Under --auto the agent can read the key, so the limit is what it can spend, and a leaked key is deleted without touching your others.

Save it outside the repo, readable only by you:

mkdir -p ~/.config/opencode-agent

install -m 600 /dev/null ~/.config/opencode-agent/openrouter.key

vi ~/.config/opencode-agent/openrouter.key

Paste the key, which starts with sk-or-, as the only line.

install with -m 600 creates the file with read and write rights for you alone before the key is in it.

2. Check that the container gets it

container/tools/ai/opencode-docker.sh --openrouter-key ~/.config/opencode-agent/openrouter.key ../site-agent shell

At the /work $ prompt:

opencode auth list

OpenRouter OPENROUTER_API_KEY environment

opencode models | grep -c '^openrouter/'

371

Without --openrouter-key the same two commands print No authenticated integrations and 0.

The ids of the models are the lines of opencode models | grep '^openrouter/', for example openrouter/deepseek/deepseek-v4.1-flash, the paid DeepSeek V4.1 Flash. Then exit.

3. Run a task on a paid model

container/tools/ai/opencode-docker.sh --openrouter-key ~/.config/opencode-agent/openrouter.key ../site-agent run -m openrouter/deepseek/deepseek-v4.1-flash "<task>"

-m picks the model for this run only; the config of step 4 (the config and the container notes) keeps the free model for every run without a key.

Which model fits which task is in AI models; prices change, so check them on OpenRouter before a long task (verify prices before budgeting).

What to know about the key

• A wrong or deleted key stops the run at the first request. With a made-up key: Error: User not found.
• Not stored anywhere in the container. The key is an environment variable of this one run. It is not written to the sessions volume, and it is not on the docker command line: while a container ran with a test key, no process on the host showed it.
• Never in the repo. A key file inside the repo or the worktree would be mounted, or committed, and the launcher refuses it: ERROR: keep the key file outside the repo and the worktree.
• Every run with the key can read it, with env, and so could a page the agent reads that tells it to send the key out. The credit limit is what protects you; runs without the option never have the key.
• Where the code goes. OpenRouter forwards each request to the provider of the model. Which providers may get your data, and whether they may keep it, is set in the privacy settings of the account (keys, limits and privacy).

Article author: Klavdiya Kondakova