> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# Use OpenAI Codex with a model on your own hardware

> Run OpenAI Codex against a local model on another machine — Ollama, LM Studio, llama.cpp, or vLLM — via Tokios, which speaks the Responses API Codex requires.

Codex CLI's custom model providers require the OpenAI **Responses** API (`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](https://docs.tokios.com/guides/openai-codex.md) 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](https://docs.tokios.com/setup/connector-install.md) installed and paired next to the model — on whichever machine that is, not the one running Codex
* A [registered deployment name](https://docs.tokios.com/setup/register-model.md) for that model
* A Tokios [API key](https://docs.tokios.com/setup/api-keys.md) (`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`:

```toml ~/.codex/config.toml theme={"theme":{"light":"github-light","dark":"css-variables"}}
[model_providers.tokios]
name = "Tokios"
base_url = "https://api.tokios.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.tokios]
model = "gemma-tunnel"
model_provider = "tokios"
disable_response_storage = true
```

Set your key in the environment before running Codex:

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
export OPENAI_API_KEY=sk-tok-YOUR_KEY
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"css-variables"}}
set OPENAI_API_KEY=sk-tok-YOUR_KEY
```

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
codex --profile tokios
```

Replace `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 need `wire_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.

> [!NOTE]
>
> `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:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
codex --profile tokios exec "Say hello in one word"
```

If you'd rather confirm the endpoint directly before involving Codex, check the [Playground](https://tokios.com/console/playground) for your deployment, or send a raw request:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/responses \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-tunnel",
    "input": "Say hello in one word"
  }'
```

## Troubleshooting

> [accordion] 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](https://tokios.com/console/keys) tab.

> [accordion] 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](https://tokios.com/console/models) tab (for example, `gemma-tunnel`) — not the upstream model id your backend uses locally.

> [accordion] 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](https://tokios.com/console/connectors) tab.

> [accordion] 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

> [card] [OpenAI Codex base setup](https://docs.tokios.com/guides/openai-codex.md)
>
> The full `config.toml` walkthrough, including the OpenAI SDK path.

> [card] [Quickstart](https://docs.tokios.com/quickstart.md)
>
> Pair a connector and register your first model end to end.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.