LunaRoute

https://docs.lunaroute.com/
Admin
LunaRoute is an LLM gateway that routes OpenAI-, Anthropic-, and Responses-shaped requests to...
Tokens:47,547
Snippets:337
Trust Score:4.9
Update:6 hours ago
Show doc for...
Tokens:
Raw
### Install LunaRoute CLI and run setup

Source: https://docs.lunaroute.com/getting-started/claude-desktop/

Install the LunaRoute CLI globally and run the setup command for Claude Desktop. Quit Claude Desktop first to avoid it overwriting your changes.

```bash
npm install -g @lunaroute/cli
lunaroute setup claude-desktop
```

--------------------------------

### Setup with --key to skip browser login

Source: https://docs.lunaroute.com/getting-started/opencode/

Use --key to skip the browser login. This verifies the key, installs the extension, and stores the key in ~/.local/share/opencode/auth.json so opencode starts signed in.

```bash
npx @lunaroute/cli setup opencode --key lr_… --yes
```

--------------------------------

### Start pi and sign in

Source: https://docs.lunaroute.com/getting-started/pi/

Start the pi interactive session. Then use /login lunaroute for browser login (if setup carried no key) and /model to pick a lunaroute/* model.

```bash
pi
```

```bash
/login lunaroute     # browser login, if setup carried no key
/model               # pick a lunaroute/* model
```

--------------------------------

### Run lunaroute setup codex and launch Codex with the lunaroute profile

Source: https://docs.lunaroute.com/getting-started/codex/

Run `lunaroute setup codex` to generate the profile file, then start Codex with `codex --profile lunaroute` to use the LunaRoute provider.

```bash
lunaroute setup codex
codex --profile lunaroute
```

--------------------------------

### lunaroute setup pi

Source: https://docs.lunaroute.com/cli/

Initializes LunaRoute for the specified harness. The command asks before writing and offers to install an extension if available, otherwise it offers to run 'lunaroute login'.

```bash
lunaroute setup pi        # or: claude-code | claude-desktop | codex | opencode | openclaw | hermes | copilot-cli | dsh | zed | generic
```

--------------------------------

### Resulting opencode.json after setup

Source: https://docs.lunaroute.com/getting-started/opencode/

The setup command merges this plugin entry into ~/.config/opencode/opencode.json. The file is JSONC and all other existing content is preserved.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@lunaroute/opencode-extension"]
}
```

--------------------------------

### Install pi coding agent

Source: https://docs.lunaroute.com/getting-started/pi/

Install the pi coding agent globally. This is required before running the setup command. The --ignore-scripts flag is used.

```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

--------------------------------

### Install CLI and sign in

Source: https://docs.lunaroute.com/getting-started/codex/

Install the LunaRoute CLI globally and sign in once. This is required before using `lunaroute run codex`.

```bash
npm install -g @lunaroute/cli
lunaroute login
lunaroute run codex
```

--------------------------------

### Install LunaRoute extension from command line

Source: https://docs.lunaroute.com/getting-started/vscode/

Run this command in the VS Code command line to install the LunaRoute extension. Equivalent to using the Extensions: Install Extensions command and searching for 'LunaRoute'.

```shell
ext install LunaRoute.lunaroute
```

--------------------------------

### Install @lunaroute/cli globally with npm

Source: https://docs.lunaroute.com/cli/

Installs the CLI globally using npm. Requires Node.js 20 or later. On Windows PowerShell, global installs land in %APPDATA%\npm and do not require sudo.

```bash
npm install -g @lunaroute/cli
```

--------------------------------

### Install the LunaRoute pi extension

Source: https://docs.lunaroute.com/getting-started/pi/

Run this command to install the @lunaroute/pi-extension. It registers the LunaRoute provider and syncs models from /v1/models at runtime. Requires pi version 0.84.1 or newer on your PATH.

```bash
npx @lunaroute/cli setup pi
```

--------------------------------

### Setup Hermes with lunaroute setup hermes

Source: https://docs.lunaroute.com/assistants/

Run this command to configure Hermes via its CLI. Hermes owns its own config, so this command drives its CLI instead of writing files.

```bash
lunaroute setup hermes
```

--------------------------------

### Setup OpenClaw with lunaroute setup openclaw

Source: https://docs.lunaroute.com/assistants/

Run this command in a terminal to merge a `lunaroute` provider into `~/.openclaw/openclaw.json`. It sets `api: openai-completions`, `baseUrl: https://gw.lunaroute.com/v1`, and reads the key from `${LUNAROUTE_API_KEY}`. Existing config is preserved; restart the gateway and verify with `openclaw models list` / `openclaw models set lunaroute/<model>`.

```bash
lunaroute setup openclaw
```

--------------------------------

### Install CLI and run Claude Code for one session

Source: https://docs.lunaroute.com/getting-started/claude-code/

Install the lunaroute CLI, sign in, and start Claude Code wired to LunaRoute for that session only. The run command sets environment variables in the child process, writes no files, and does not modify ~/.claude/. Requires a stored login; a LUNAROUTE_API_KEY is not sufficient and will cause a 'Not logged in' error. Claude Code must already be installed.

```bash
npm install -g @lunaroute/cli
lunaroute login
lunaroute run claude-code
```

--------------------------------

### lunaroute setup pi --key lr_… --yes

Source: https://docs.lunaroute.com/cli/

Sets up LunaRoute non-interactively using an existing API key and accepting all prompts. Useful for automated setups.

```bash
lunaroute setup pi --key lr_… --yes
```

--------------------------------

### web_search response example

Source: https://docs.lunaroute.com/mcp/web-search/

Example JSON response from the web_search tool. The result shape is identical across providers. An empty results array is a valid answer, not an error.

```json
{
  "query": "rust async cancellation patterns",
  "provider": "brave",
  "results": [
    {
      "title": "…",
      "url": "…",
      "snippet": "…",
      "published_date": "2026-08-01",
      "score": 0.87
    }
  ]
}
```

--------------------------------

### Remove LunaRoute Claude Desktop setup

Source: https://docs.lunaroute.com/getting-started/claude-desktop/

Run this command in a terminal to undo the LunaRoute Claude Desktop setup. It restores the profile snapshot taken before setup, byte-for-byte, including any pre-existing keys. It requires no login and is idempotent. If no snapshot exists, it prints the keys it would remove and changes nothing; add --print to preview without modifying the file.

```bash
lunaroute setup claude-desktop --remove
```

--------------------------------

### web_search request example

Source: https://docs.lunaroute.com/mcp/web-search/

Example JSON payload for calling the web_search MCP tool. The query is required (1-400 characters), provider is optional (defaults to organization default), and count is clamped to provider's supported range.

```json
{
  "query": "rust async cancellation patterns",
  "provider": "brave",
  "count": 5
}
```

--------------------------------

### curl GET /v1/models with X-LunaRoute-Client: claude-desktop

Source: https://docs.lunaroute.com/api/models/

Fetches the Claude Desktop variant of the model catalog using the X-LunaRoute-Client header. Returns an Anthropic-shaped catalog of Claude-compatible aliases.

```bash
curl https://gw.lunaroute.com/v1/models \
  -H "Authorization: Bearer $LUNAROUTE_API_KEY" \
  -H "X-LunaRoute-Client: claude-desktop"
```

--------------------------------

### Log in and pick a model inside opencode

Source: https://docs.lunaroute.com/getting-started/opencode/

Use /connect to log in via browser (PKCE) if setup didn't carry a key, and /models to pick a lunaroute/* model. Models auto-sync from /v1/models.

```bash
/connect      # browser login, if setup carried no key
/models       # pick a lunaroute/* model
```

--------------------------------

### Verify LunaRoute API key with curl

Source: https://docs.lunaroute.com/getting-started/codex/

Use this curl command to verify the LunaRoute API key and endpoint before starting Codex. It sends a GET request to the models catalog at https://gw.lunaroute.com/v1/models with the API key in the Authorization header. The key must be set in the LUNAROUTE_API_KEY environment variable.

```bash
curl https://gw.lunaroute.com/v1/models \
  -H "Authorization: Bearer $LUNAROUTE_API_KEY"
```

--------------------------------

### Run LunaRoute setup for opencode

Source: https://docs.lunaroute.com/getting-started/opencode/

Run this command to add the @lunaroute/opencode-extension plugin to opencode. It merges the plugin entry into ~/.config/opencode/opencode.json and preserves existing settings. If you use a non-default gateway, it also pins provider.lunaroute.options.baseURL.

```bash
npx @lunaroute/cli setup opencode
```

--------------------------------

### Setup generic OpenAI-compatible agent

Source: https://docs.lunaroute.com/assistants/

Run this command to configure NanoClaw or any generic OpenAI-compatible agent. It prints the base URL and the `LUNAROUTE_API_KEY` export. Use base URL `https://gw.lunaroute.com/v1` and your `lr_` key.

```bash
lunaroute setup generic     # prints the base URL and the LUNAROUTE_API_KEY export
```

--------------------------------

### Export LUNAROUTE_API_KEY for shell profile

Source: https://docs.lunaroute.com/getting-started/opencode/

When you decline the extension, setup also outputs this export line to paste into your shell profile. It sets the environment variable used by the static provider block.

```bash
export LUNAROUTE_API_KEY=…
```

--------------------------------

### Run Zed with LUNAROUTE_API_KEY injected

Source: https://docs.lunaroute.com/getting-started/zed/

Use this command to launch Zed with the LUNAROUTE_API_KEY added to its environment. It only injects the key; the provider block still comes from settings.json. Quit any running Zed first, as the variable only reaches a new process.

```bash
npx @lunaroute/cli run zed
```

--------------------------------

### GET /v1/models

Source: https://docs.lunaroute.com/getting-started/first-request/

Lists the available models.

```APIDOC
## GET /v1/models

### Description
Lists the available models.

### Method
GET

### Endpoint
https://gw.lunaroute.com/v1/models

### Parameters
#### Headers
- **LUNAROUTE-API-KEY** (string) - Required - Your LunaRoute API key.

### Request Example
```
curl https://gw.lunaroute.com/v1/models \
  -H "LUNAROUTE-API-KEY: $LUNAROUTE_API_KEY"
```

### Response
List of models.

```

--------------------------------

### CLI setup command for LunaRoute harness

Source: https://docs.lunaroute.com/mcp/harnesses/

Run this command to automatically configure the selected harness. Supported harnesses: pi, claude-code, codex, claude-desktop, opencode, openclaw, hermes, copilot-cli, dsh, zed, and generic.

```bash
npx @lunaroute/cli setup <harness>
```

--------------------------------

### GET /v1/images/{id}

Source: https://docs.lunaroute.com/api/images/

Retrieves metadata for a specific image by its ID.

```APIDOC
## GET /v1/images/{id}

### Description
Retrieves metadata for a specific image by its ID.

### Method
GET

### Endpoint
/v1/images/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the image.

### Response
#### Success Response (200)
- **id** (string) - The image ID.
- **created_at** (string) - The creation timestamp.
- **expires_at** (string) - The expiration timestamp.

#### Response Example
{
  "id": "img_123",
  "created_at": "2025-01-01T00:00:00Z",
  "expires_at": "2025-01-08T00:00:00Z"
}
```

--------------------------------

### upload_image Tool

Source: https://docs.lunaroute.com/mcp/

Uploads a local image (or URL) and gets an id to edit.

```APIDOC
## upload_image Tool

### Description
Upload a local image (or URL) and get an id to edit.

### Tool Name
`upload_image`

### Access Policy
- Organization admins can allow or deny this tool per user or org-wide.
- A denied call returns the tool error `mcp_tool_disabled`.
- Availability: omitted from `tools/list` when the image runtime or entitlement is unavailable.
```

--------------------------------

### Configure a coding agent with @lunaroute/cli setup

Source: https://docs.lunaroute.com/getting-started/

Run this command to configure your coding agent (e.g., pi, claude-code, opencode) to use LunaRoute. The command supports multiple agent names as shown in the comment.

```bash
npx @lunaroute/cli setup pi      # or: claude-code | claude-desktop | codex | opencode | openclaw | hermes | copilot-cli | zed | generic
```

--------------------------------

### Profile file keys for manual configuration

Source: https://docs.lunaroute.com/getting-started/claude-desktop/

Merge these keys into the profile file created by Claude Desktop. The X-LunaRoute-Client header selects LunaRoute's Claude-compatible catalog; without it, Desktop filters out the normal catalog. Do not add an inferenceModels list, as it disables discovery and results in an empty picker.

```json
{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://gw.lunaroute.com",
  "inferenceGatewayApiKey": "lr_your_key_here",
  "inferenceGatewayAuthScheme": "bearer",
  "modelDiscoveryEnabled": true,
  "inferenceCustomHeaders": { "X-LunaRoute-Client": "claude-desktop" }
}
```

--------------------------------

### POST /v1/images/uploads

Source: https://docs.lunaroute.com/api/images/

Uploads an image URL or bytes and gets an id to edit.

```APIDOC
## POST /v1/images/uploads

### Description
Uploads an image URL or bytes and gets an id to edit.

### Method
POST

### Endpoint
/v1/images/uploads

### Parameters
#### Request Body
- **url** (string) - Optional - The URL of the image to upload.
- **bytes** (binary) - Optional - The raw bytes of the image.

### Request Example
{
  "url": "https://example.com/image.png"
}

### Response
#### Success Response (200)
- **id** (string) - The ID of the uploaded image.

#### Response Example
{
  "id": "img_789"
}
```

--------------------------------

### List chat models and pricing with CLI

Source: https://docs.lunaroute.com/models/

Use the lunaroute CLI to list available chat models and per-model credit pricing. The CLI listing is chat-only and omits image, embedding, rerank, and decision models.

```bash
lunaroute models     # available models
lunaroute pricing    # per-model credit pricing
```

--------------------------------

### GET /v1/images/models

Source: https://docs.lunaroute.com/api/images/

Retrieves the image-capable model catalog, including supported sizes, steps range, and formats.

```APIDOC
## GET /v1/images/models

### Description
Retrieves the image-capable model catalog, including supported sizes, steps range, and formats.

### Method
GET

### Endpoint
/v1/images/models

### Response
#### Success Response (200)
- **models** (array of objects) - List of available models.

#### Response Example
{
  "models": [
    {
      "id": "model-1",
      "sizes": ["1024x1024"],
      "steps_range": [1, 50],
      "formats": ["png", "jpeg"]
    }
  ]
}
```

--------------------------------

### GET /v1/rerank/models

Source: https://docs.lunaroute.com/api/embeddings-rerank/

Lists the models available for the rerank task with their declared limits and the organization's effective policy.

```APIDOC
## GET /v1/rerank/models

### Description
Lists the models available for the rerank task with their declared limits and the organization's effective policy.

### Method
GET

### Endpoint
/v1/rerank/models

### Response
#### Success Response (200)
- **models** (array) - List of models with their declared limits.
- **policy** (object) - The organization's effective policy.

### Errors
- **503** - `embeddings_disabled` if the feature is switched off.
```

--------------------------------

### GET /v1/embeddings/models

Source: https://docs.lunaroute.com/api/embeddings-rerank/

Lists the models available for the embeddings task with their declared limits and the organization's effective policy.

```APIDOC
## GET /v1/embeddings/models

### Description
Lists the models available for the embeddings task with their declared limits and the organization's effective policy.

### Method
GET

### Endpoint
/v1/embeddings/models

### Response
#### Success Response (200)
- **models** (array) - List of models with their declared limits.
- **policy** (object) - The organization's effective policy.

### Errors
- **503** - `embeddings_disabled` if the feature is switched off.
```

--------------------------------

### GET /v1/models

Source: https://docs.lunaroute.com/api/systemone/

Lists decision models alongside chat models. Decision models are discoverable through this shared catalog endpoint.

```APIDOC
## GET /v1/models

### Description
Lists decision models alongside chat models. Decision models are discoverable through this shared catalog endpoint.

### Method
GET

### Endpoint
/v1/models

### Parameters
None explicitly documented.

### Request Example
No request body required.

### Response
#### Success Response (200)
A list of models including decision models and chat models.

#### Response Example
No example provided.

### Errors
| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `systemone_invalid_request` | Structural validation failed — bad question type, criteria shape, over a model limit, or the model cannot serve decisions (e.g. a chat-model id). |
| 402 | `insufficient_credits` / `reservation_too_large` | Wallet refused the reservation; `reservation_too_large` names the organization bound as `credits_bound`. |
| 403 | `systemone_policy_disabled` | Decision models are not enabled for your organization or plan. |
| 404 | `model_not_found` | Unknown model id. |
| 408 | `body_read_timeout` | The request body was not received within the slow-body timeout. |
| 413 | `payload_too_large` | Request body over the size cap. |
| 415 | `unsupported_content_encoding` | Compressed request bodies are not accepted. |
| 429 | `systemone_gate_busy` / `systemone_backend_busy` | Decision capacity is busy (`gate_busy`), or the upstream is rate-limiting (`backend_busy`) — carries `Retry-After`. |
| 502 | `systemone_backend_error` | The upstream failed or answered unusable (5xx, malformed, or over cap). |
| 503 | `systemone_disabled` | The feature is switched off platform-side. |
| 503 | `systemone_models_unavailable` and siblings | Temporary platform-side unavailability (catalog, policy, billing, draining). |
| 504 | `systemone_deadline_exceeded` | The request outlived its deadline. |
```
Tokens:
Raw