wire_api = "responses"), and Codex’s built-in Ollama provider only reaches localhost — it can’t target a model on another machine. Tokios serves /v1/responses and translates it to Chat Completions for your backend, so a remote box running Ollama, llama.cpp, vLLM, or LM Studio works as a Codex provider over a normal https endpoint.
This page assumes you already have Tokios and Codex working together — see Use OpenAI Codex with your own local models for the full config.toml walkthrough. Read on if your model lives on a different machine than the one running Codex, or if you’re troubleshooting a provider that won’t connect.
Prerequisites
- A connector installed and paired next to the model — on whichever machine that is, not the one running Codex
- A registered deployment name for that model
- A Tokios API key (
sk-tok-…) - Codex CLI installed on the machine where you run
codex
Configure Codex
The provider config is the same whether the model is next to you or across the network — Tokios is what makes the location not matter. In~/.codex/config.toml:
~/.codex/config.toml
gemma-tunnel with the deployment name you registered for the remote model — not its local upstream model id, and not a localhost address.
Why this works when localhost doesn’t
Codex’s custom providers needwire_api = "responses" — Codex speaks the Responses API to any provider you configure, and its built-in Ollama provider is documented to hardcode a localhost base URL, so it can’t point at a model on another machine.
Two things have to be true at once for a remote model to work as a Codex provider: the endpoint has to answer the Responses API, and it has to be a stable https address Codex can reach from wherever it runs. Most local inference servers — Ollama, llama.cpp, vLLM, LM Studio — only speak Chat Completions, not Responses. The Tokios gateway sits in front of your connector, accepts /v1/responses from Codex, and translates it to Chat Completions before it reaches your backend. Your backend never needs to know Responses exists, and Codex never needs a localhost provider — it talks to https://api.tokios.com/v1 regardless of which machine, network, or connector is behind it.
disable_response_storage = true is required alongside wire_api = "responses". Tokios serves the Responses surface statelessly, so Codex must not rely on server-side response storage between turns.Verify it’s working
Run a quick prompt through the profile:Troubleshooting
401 — missing or invalid API key
401 — missing or invalid API key
Codex isn’t sending a key Tokios recognizes. Confirm
OPENAI_API_KEY is set to your sk-tok-… key in the same shell you launch codex from, and that the key hasn’t been rotated or disabled on the Keys tab.404 — model deployment not found
404 — model deployment not found
The
model value in [profiles.tokios] doesn’t match a registered deployment. It must be the public name you chose on the Models tab (for example, gemma-tunnel) — not the upstream model id your backend uses locally.503 — connector offline or at capacity
503 — connector offline or at capacity
The connector paired with that deployment isn’t currently connected, or it’s at its concurrency cap (
connector_unavailable / connector_busy). Check that the connector process is running on the machine next to the model and shows Online on the Connectors tab.Codex falls back to a built-in provider instead of Tokios
Codex falls back to a built-in provider instead of Tokios
Confirm you’re launching with
--profile tokios. Without a profile flag, Codex uses its default provider, not the one in [model_providers.tokios].Next steps
OpenAI Codex base setup
The full
config.toml walkthrough, including the OpenAI SDK path.Quickstart
Pair a connector and register your first model end to end.