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

# Coding Agents

The LithosAI API supports many coding agents, including Codex, Claude Code, and
OpenCode. OpenCode connects directly. Codex and Claude Code each require a
different protocol, so a local translation proxy is needed.

| Agent                       | Expects                | Connects        |
| --------------------------- | ---------------------- | --------------- |
| [Codex](#codex)             | Responses API          | Through a proxy |
| [Claude Code](#claude-code) | Anthropic Messages API | Through a proxy |
| [OpenCode](#opencode)       | Chat Completions       | Directly        |

Export your key once, in whichever shell you use to start these tools.

```bash theme={null}
export LITHOSAI_API_KEY="your-key"
```

<Note>
  LithosAI validates tool schemas strictly. An agent that loads an MCP server whose tool
  parameters are not a JSON Schema object is rejected with `invalid 'parameters' schema`.
  Disable that server or correct its schema.
</Note>

## Codex

Codex no longer speaks Chat Completions. `wire_api = "chat"` is rejected at startup, and
`responses` is the only accepted value, so Codex reaches LithosAI through a proxy that
accepts Responses API requests.

<Steps>
  <Step title="Install LiteLLM">
    [LiteLLM](https://docs.litellm.ai) bridges the Responses API to Chat Completions.

    ```bash theme={null}
    pip install 'litellm[proxy]'
    ```

    <Warning>
      Install a current release. LiteLLM 1.82.7 and 1.82.8 were briefly replaced on PyPI in
      March 2026 by a [credential stealer](https://docs.litellm.ai/blog/security-update-march-2026).
    </Warning>
  </Step>

  <Step title="Configure the proxy">
    Give the model the `openai/` prefix and set `use_chat_completions_api`, which bridges
    incoming `/v1/responses` requests to LithosAI's `/v1/chat/completions`.

    ```yaml codex.litellm.yaml theme={null}
    model_list:
      - model_name: kimi-k3
        litellm_params:
          model: openai/moonshotai/Kimi-K3
          api_base: https://api.lithosai.cloud/v1
          api_key: os.environ/LITHOSAI_API_KEY
          use_chat_completions_api: true

    litellm_settings:
      drop_params: true

    general_settings:
      master_key: sk-codex-proxy
    ```

    `drop_params` discards parameters a model does not accept rather than failing the
    request. `master_key` is the token Codex sends to the proxy, not your LithosAI key.
  </Step>

  <Step title="Start the proxy">
    ```bash theme={null}
    litellm --config codex.litellm.yaml --port 4000
    ```

    Leave it running, and confirm it is up. The proxy holds your LithosAI key, so keep it
    bound to `127.0.0.1` and do not expose it to a network.

    ```bash theme={null}
    curl http://127.0.0.1:4000/health/liveliness
    ```
  </Step>

  <Step title="Point Codex at it">
    ```toml ~/.codex/config.toml theme={null}
    model = "kimi-k3"
    model_provider = "lithosai"

    [model_providers.lithosai]
    name = "LithosAI"
    base_url = "http://127.0.0.1:4000/v1"
    env_key = "LITELLM_API_KEY"
    wire_api = "responses"
    requires_openai_auth = false
    ```

    `env_key` names the variable holding the proxy's `master_key`, so export that too.

    ```bash theme={null}
    export LITELLM_API_KEY="sk-codex-proxy"
    codex
    ```
  </Step>
</Steps>

### Troubleshooting

| Symptom                                    | Cause                                                                                                             |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `wire_api = "chat"` is no longer supported | `base_url` points at LithosAI directly. Point it at the proxy.                                                    |
| `404` on `/v1/responses`                   | The model entry uses `hosted_vllm/`. Codex needs `openai/` with `use_chat_completions_api`.                       |
| `400` with `No connected db.`              | `LITELLM_API_KEY` does not match the proxy's `master_key`. LiteLLM reports the lookup failure, not an auth error. |

## Claude Code

Claude Code speaks the Anthropic Messages API, so its proxy needs a different configuration
from the one Codex uses. Run it on a second port to use both agents at once.

<Steps>
  <Step title="Install LiteLLM">
    [LiteLLM](https://docs.litellm.ai) bridges the Anthropic Messages API to Chat
    Completions.

    ```bash theme={null}
    pip install 'litellm[proxy]'
    ```

    <Warning>
      Install a current release. LiteLLM 1.82.7 and 1.82.8 were briefly replaced on PyPI in
      March 2026 by a [credential stealer](https://docs.litellm.ai/blog/security-update-march-2026).
    </Warning>
  </Step>

  <Step title="Configure the proxy">
    Give each model the `hosted_vllm/` prefix. It routes `/v1/messages` straight to Chat
    Completions and maps replies, including reasoning, back into Anthropic content blocks.

    ```yaml claude-code.litellm.yaml theme={null}
    model_list:
      - model_name: kimi-k3
        litellm_params:
          model: hosted_vllm/moonshotai/Kimi-K3
          api_base: https://api.lithosai.cloud/v1
          api_key: os.environ/LITHOSAI_API_KEY
      - model_name: kimi-k3-fast
        litellm_params:
          model: hosted_vllm/moonshotai/Kimi-K3-fast
          api_base: https://api.lithosai.cloud/v1
          api_key: os.environ/LITHOSAI_API_KEY

    litellm_settings:
      drop_params: true

    general_settings:
      master_key: sk-claude-proxy
    ```

    <Warning>
      Do not reuse the Codex configuration here. An `openai/` entry with
      `use_chat_completions_api` answers `/v1/messages` with `200 OK` and empty content, so
      Claude Code appears to hang rather than reporting an error.
    </Warning>
  </Step>

  <Step title="Start the proxy">
    ```bash theme={null}
    litellm --config claude-code.litellm.yaml --port 4001
    ```

    Leave it running, and confirm it is up. The proxy holds your LithosAI key, so keep it
    bound to `127.0.0.1` and do not expose it to a network.

    ```bash theme={null}
    curl http://127.0.0.1:4001/health/liveliness
    ```
  </Step>

  <Step title="Point Claude Code at it">
    ```bash theme={null}
    export ANTHROPIC_BASE_URL="http://127.0.0.1:4001"
    export ANTHROPIC_AUTH_TOKEN="sk-claude-proxy"
    export ANTHROPIC_MODEL="kimi-k3"
    export ANTHROPIC_SMALL_FAST_MODEL="kimi-k3-fast"
    claude
    ```

    `ANTHROPIC_SMALL_FAST_MODEL` handles background work such as session titles. Without it,
    those requests fail against a model the proxy does not serve.

    <Warning>
      Setting `ANTHROPIC_AUTH_TOKEN` overrides a Claude.ai login for that shell. Export these
      in a dedicated shell or profile to keep an existing subscription usable elsewhere.
    </Warning>
  </Step>
</Steps>

Claude Code does not recognize LithosAI model names, so it assumes a 200k-token context
window and compacts early. Set the real window to avoid that.

```bash theme={null}
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=262144
```

<Note>
  Check the [Models](https://console.lithosai.cloud/models) console page for each model's
  context window.
</Note>

### Troubleshooting

| Symptom                                       | Cause                                                                                                                  |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Empty replies, or the session appears to hang | The model entry uses `openai/` with `use_chat_completions_api`. Claude Code needs `hosted_vllm/`.                      |
| Background requests fail while chat works     | `ANTHROPIC_SMALL_FAST_MODEL` is unset or names a model the proxy does not serve.                                       |
| `400` with `No connected db.`                 | `ANTHROPIC_AUTH_TOKEN` does not match the proxy's `master_key`. LiteLLM reports the lookup failure, not an auth error. |

## OpenCode

OpenCode reaches LithosAI directly, with no proxy and nothing to install. Declare the
provider in `opencode.json`, either in a project or at `~/.config/opencode/opencode.json`.

```json opencode.json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lithosai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LithosAI",
      "options": {
        "baseURL": "https://api.lithosai.cloud/v1",
        "apiKey": "{env:LITHOSAI_API_KEY}"
      },
      "models": {
        "moonshotai/Kimi-K3": { "name": "Kimi K3" },
        "moonshotai/Kimi-K3-fast": { "name": "Kimi K3 fast" }
      }
    }
  },
  "model": "lithosai/moonshotai/Kimi-K3"
}
```

`@ai-sdk/openai-compatible` is the package for Chat Completions providers, and OpenCode
bundles it. Start OpenCode as usual.

```bash theme={null}
opencode
```