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

# Novita Connect

> Run Claude Code, Codex, OpenCode, Pi and DeepSeek Harness on Novita models with one command.

Novita Connect plugs Novita models into the coding harness you already use. Keep your tools, workflow and shortcuts; switch the model underneath with one command, and switch back by simply running your harness as usual.

<Frame>
  <video autoPlay muted loop playsInline preload="metadata" poster="/images/novita-connect/novita-connect-poster.webp" className="w-full aspect-video rounded-xl">
    <source src="https://mintcdn.com/novitaai/Xux9kgg0InaknZco/images/novita-connect/novita-connect-loop.webm?fit=max&auto=format&n=Xux9kgg0InaknZco&q=85&s=d0672d1cd863d1439815b13c9020b08e" type="video/webm" data-path="images/novita-connect/novita-connect-loop.webm" />

    <source src="https://mintcdn.com/novitaai/Xux9kgg0InaknZco/images/novita-connect/novita-connect-loop.mp4?fit=max&auto=format&n=Xux9kgg0InaknZco&q=85&s=ba8907d8c02f9774141c5f7f8b701158" type="video/mp4" data-path="images/novita-connect/novita-connect-loop.mp4" />

    <img src="https://mintcdn.com/novitaai/Xux9kgg0InaknZco/images/novita-connect/novita-connect.webp?fit=max&auto=format&n=Xux9kgg0InaknZco&q=85&s=aa216c26023e9b6d544fc0da7da18dfb" alt="Novita Connect connects coding harnesses to Novita models" width="1600" height="900" data-path="images/novita-connect/novita-connect.webp" />
  </video>
</Frame>

The CLI is called `novi`. It starts your harness with Novita settings injected for that session only, so your own configuration is left untouched.

<Note>
  Novita Connect is currently in **Beta**. Commands and the default model lineup may change. It runs on macOS and Linux (amd64 and arm64).
</Note>

## Requirements

* A Novita API key from [Key Management](https://novita.ai/settings/key-management).
* macOS or Linux with `curl`.
* The harness you want to use. If it isn't installed, the `novi` menu shows installation instructions and an official download link.

## Quickstart

<Steps>
  <Step title="Install novi">
    ```bash theme={"system"}
    curl -fsSL https://novita.ai/connect/install.sh | sh
    ```

    The installer puts `novi` in `~/.local/bin`, verifies the download against `SHA256SUMS`, and installs the latest release.
  </Step>

  <Step title="Log in with your Novita API key">
    ```bash theme={"system"}
    novi login
    ```

    Paste a key from [Key Management](https://novita.ai/settings/key-management). You can also set `NOVITA_API_KEY` instead of saving a key.
  </Step>

  <Step title="Start a harness">
    ```bash theme={"system"}
    novi claude
    ```

    Claude Code starts on Novita models. Run `novi` on its own to open the interactive menu and pick a harness, browse models, or check your balance.
  </Step>
</Steps>

### Installer options

| Variable | Effect |
| - | - |
| `NOVI_INSTALL_DIR` | Install somewhere other than `~/.local/bin` |
| `NOVI_VERSION=x.y.z` | Pin a specific release instead of the latest |

```bash theme={"system"}
curl -fsSL https://novita.ai/connect/install.sh | NOVI_VERSION=0.3.0 sh
```

## Supported harnesses

| Harness | How to start | Your config |
| - | - | - |
| Claude Code | `novi claude` | Untouched |
| Codex | `novi codex` | Untouched |
| OpenCode | `novi opencode` | Per-process provider |
| Pi | `novi pi` | Temporary provider extension |
| DeepSeek Harness | `novi dsh` | Temporary patch overlay |
| Claude Desktop (Beta) | Menu → Launch desktop app | Long-term setup; Disconnect restores |
| Codex Desktop (Beta) | Menu → Launch / One-time use | Long-term setup or isolated instance |

`--model` and `--print-env` go right after the harness name; everything else is passed through to the harness:

```bash theme={"system"}
novi codex --model zai-org/glm-5.3
novi claude --print-env   # show what would be injected, secrets masked
```

OpenCode, Pi and DeepSeek Harness use Novita Chat Completions through the same local relay. OpenCode and Pi keep their original providers and model selections alongside Novita, and all generated provider files are removed on exit. `novi dsh` starts the web profile; use `novi dsh headless "task"` or `novi dsh --profile <name>` to choose another profile.

<AccordionGroup>
  <Accordion title="Claude Code and an existing claude.ai login">
    Claude Code preserves an existing claude.ai login and custom model picker; otherwise it uses the relay token. Its default model and tier aliases point to Novita during the session. Preserving the login does not provide automatic Anthropic subscription passthrough.
  </Accordion>

  <Accordion title="Codex and an existing ChatGPT login">
    When Codex's `auth.json` contains an access token, its original models and Novita models share the picker. Original model requests go to OpenAI with the client's credential; Novita requests use only the Novita key. Without a ChatGPT login, `novi` uses a standalone Novita provider. A login stored only in a system keychain is not yet detected.
  </Accordion>

  <Accordion title="Harness version requirements">
    DeepSeek Harness requires a version with `--patch` support (verified with 0.2.0-rc.2). Pi requires its provider extension API. OpenCode 2 runs with a private server so it inherits the session configuration.
  </Accordion>
</AccordionGroup>

## Models

Every Novita model the harness can use appears in its own model picker (`/model`), with prices and context sizes. The default lineup:

| Role | Model |
| - | - |
| Main | `moonshotai/kimi-k3` |
| Mid | `zai-org/glm-5.3` |
| Background tasks | `deepseek/deepseek-v4.1-flash` |

Pick another model for a session with `--model <id>`, and list everything available with prices:

```bash theme={"system"}
novi models
```

Tools, MCP servers, subagents and web search keep working on Novita models, and so does Codex's tool search. Web search runs through [Novita AI Search](/guides/ai-search-quickstart) and is billed to your account; set `NOVI_NO_WEB_SEARCH=1` to turn it off.

## How your key stays safe

* **Your key stays with `novi`.** Each session runs through a local relay on `127.0.0.1`. The harness only gets a session token that works there, so neither the harness nor anything it runs can read your Novita API key.
* **Nothing is left behind.** CLI sessions inject everything into the harness process. Settings a harness saves on its own during the session (model, effort) are put back when it exits.

## Desktop apps (Beta)

On macOS, `novi` can connect Claude Desktop and Codex Desktop to Novita. Open the `novi` menu and choose the app, or run:

```bash theme={"system"}
novi codex-desktop     # launch; first use saves long-term setup (macOS)
novi claude-desktop    # same launch behavior for Claude Desktop (macOS)
```

* **Launch desktop app** opens the app with a long-term Novita setup, and reuses an existing setup instead of reconfiguring every time. The setup keeps one background relay on `127.0.0.1:17861` for both apps.
* **One-time use** (Codex Desktop only, experimental) starts an isolated instance with its own `CODEX_HOME` and app data. Your original configuration stays untouched; you may need to complete first-run setup.
* **Disconnect / restore settings** (press **m** in the menu for connection management) puts back what `novi` changed and keeps your later edits. Every change is journaled.

<Warning>
  Claude Desktop runs in third-party gateway mode with a Novita profile. Cloud sessions and Remote Control are unavailable in this mode, and earlier Anthropic conversations stay in the original data directory. Use **Switch to official Claude** to go back while keeping the Novita profile for later.
</Warning>

On Linux, use **Connect / start** in the menu, then quit and reopen the app yourself. Run `novi desktop status` for desktop app and connection diagnostics.

## Usage receipts

CLI sessions print a receipt on stderr when they exit, without changing the agent's stdout. To summarize locally observed input, output and cache tokens by model:

```bash theme={"system"}
novi usage --last 7d
```

Add `--json` for request-level records. Usage metadata is stored privately under `~/.config/novi/usage`; no prompts, response text, credentials or working directories are recorded.

<Note>
  Totals are estimates based on the catalog price at request time, not your actual Novita bill, and exclude search and other charges. Check your [billing page](/guides/llm-billing) for actual charges.
</Note>

## Commands

| Command | Description |
| - | - |
| `novi` | Interactive menu |
| `novi login` | Save your Novita API key (or set `NOVITA_API_KEY`) |
| `novi claude [--model M] [args…]` | Start Claude Code on Novita |
| `novi codex [--model M] [args…]` | Start Codex on Novita |
| `novi opencode [--model M] [args…]` | Start OpenCode on Novita |
| `novi pi [--model M] [args…]` | Start Pi on Novita |
| `novi dsh [--model M] [args…]` | Start DeepSeek Harness on Novita |
| `novi models` | Model list with prices |
| `novi doctor` | Key, connectivity, harness versions and updates |
| `novi usage [--last 7d] [--json]` | Local usage history (estimated model cost) |
| `novi update --check` | Check for a new `novi` release |
| `novi update` | Verified in-place update to the latest release |
| `novi desktop status` | Desktop app and connection diagnostics |
| `novi desktop disconnect --all` | Restore both desktop connections |
| `novi uninstall [--yes]` | Remove `novi` and everything it added |
| `novi <harness> --print-env` | Show what would be injected (secrets masked) |
| `novi version` | Print the installed version |

## Environment variables

| Variable | Effect |
| - | - |
| `NOVITA_API_KEY` | Key to use instead of the saved one |
| `NOVI_NO_WEB_SEARCH=1` | Turn off web search |
| `NOVI_NO_UPDATE_CHECK=1` | Don't look up the latest harness versions |
| `NOVI_NPM_REGISTRY` | npm registry mirror for version lookups |
| `NOVI_CODEX_APPLY_PATCH=freeform` | Experimental: Codex's freeform `apply_patch` tool |
| `NOVI_NO_ANIMATION=1` / `NO_COLOR=1` | Static menu |
| `NOVI_NOVITA_DIRECT=1` | Bypass your proxy for `api.novita.ai` only |
| `NOVI_RELAY_DUMP=<file>` | Debug: log relay requests (never credentials) |

## Update and uninstall

```bash theme={"system"}
novi update
```

`novi update` downloads the latest release, verifies its checksum and version, then replaces `novi` in place. A running desktop relay is restarted on the new binary. To go back, reinstall a specific version with `NOVI_VERSION=x.y.z` and the installer.

```bash theme={"system"}
novi uninstall
```

Uninstall restores desktop connections, then removes `novi` and `~/.config/novi/`. Your harness configs and session history stay. Usage history and recovery backups are preserved; remove them separately if you no longer need them.

## Known limitations

* Tested with Claude Code 2.1.283–2.1.295 and Codex 0.153.4–0.162.0. `novi doctor` flags older versions.
* Codex conversations started through `novi` can't be resumed with plain `codex resume`.
* Codex's own sandbox needs unprivileged user namespaces, which Ubuntu 24.04 blocks by default.
* Claude Desktop gateway mode does not use Anthropic sign-in; Remote Control and other features that require the official endpoint are unavailable.
* macOS and Linux only.

## FAQ

<AccordionGroup>
  <Accordion title="Does Novita Connect change my harness configuration?">
    No. CLI sessions inject Novita settings into the harness process only, and settings the harness saves on its own during the session are put back when it exits. To use your harness without Novita, run it as usual (for example `claude` instead of `novi claude`).
  </Accordion>

  <Accordion title="Can the harness see my Novita API key?">
    No. The harness talks to a local relay on `127.0.0.1` using a session token that only works there. Your API key stays with `novi`.
  </Accordion>

  <Accordion title="How do I use a different model?">
    Pass `--model <id>` right after the harness name, for example `novi claude --model zai-org/glm-5.3`, or switch inside the harness with `/model`. Run `novi models` to see every available model with prices.
  </Accordion>

  <Accordion title="My proxy can't reach Novita. What can I do?">
    If direct access works, run `NOVI_NOVITA_DIRECT=1 novi` to bypass the proxy for `api.novita.ai` only. Set `"novita_direct": true` in `novi`'s `config.json` to persist this, including for the background desktop relay.
  </Accordion>

  <Accordion title="Something isn't working. Where do I start?">
    Run `novi doctor`. It checks your key, connectivity, harness versions and updates, and includes desktop app paths, configuration paths and connection status.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Claude Code" icon="terminal" href="/guides/claude-code">
    Configure Claude Code manually with Novita's Anthropic-compatible API.
  </Card>

  <Card title="Codex" icon="terminal" href="/guides/codex">
    Configure Codex manually with Novita's OpenAI-compatible API.
  </Card>
</CardGroup>


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