OpenCodex

https://opencodex.me
Admin
OpenCodex is a local proxy that serves Codex and Claude Code from one port, translating wire formats...
Tokens:46,481
Snippets:660
Trust Score:4.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and start the opencodex proxy

Source: https://opencodex.me/

Basic commands to install the global npm package and initiate the proxy server.

```zsh
$ npm install -g @bitkyc08/opencodex  # Install
$ ocx start  # Start the proxy
```

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

### Initialize Development Environment

Source: https://opencodex.me/contributing

Commands to clone the repository, install dependencies, and start the development servers.

```bash
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy    # proxy API in dev mode
bun run dev:gui      # dashboard dev server (another terminal)
bun run typecheck    # bun x tsc --noEmit
bun run test         # bun test ./tests/
```

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

### Start server with remote access token

Source: https://opencodex.me/reference/configuration/server

Export the authentication token as an environment variable before starting the server to allow non-loopback binds.

```bash

export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
ocx start

```

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

### Install preview release

Source: https://opencodex.me/getting-started/installation

Commands to install and update to the preview release channel for testing unreleased builds.

```bash
npm install -g @bitkyc08/opencodex@preview
ocx update --tag preview
```

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

### Install OpenCode CLI

Source: https://opencodex.me/guides/opencode

Use npm to install the OpenCode package globally on your system.

```bash
npm install -g opencode-ai
```

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

### Run Documentation Site

Source: https://opencodex.me/contributing

Commands to navigate to the documentation directory and start the development server.

```bash
cd docs-site && bun install && bun dev
```

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

### Install opencodex globally

Source: https://opencodex.me/getting-started/installation

Standard installation command for the opencodex package via npm.

```bash
npm install -g @bitkyc08/opencodex
```

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

### Verify installation

Source: https://opencodex.me/getting-started/installation

Check that the command aliases are correctly installed and available on your system path.

```bash
ocx --version
opencodex --version
```

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

### Install and Verify OpenCodex

Source: https://opencodex.me/getting-started/for-agents

Installs the package globally and verifies the installation by checking the version.

```bash
npm install -g @bitkyc08/opencodex
ocx --version
```

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

### Initialize OpenCodex

Source: https://opencodex.me/getting-started/quickstart

Run the setup wizard to configure providers, API keys, and proxy settings.

```bash
ocx init
```

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

### Run from source

Source: https://opencodex.me/getting-started/installation

Steps to clone the repository and start the development proxy and dashboard servers.

```bash
git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy   # starts the proxy API in dev mode (src/cli/index.ts start)
bun run dev:gui     # starts the dashboard dev server (another terminal)
```

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

### Model Slug Examples

Source: https://opencodex.me/guides/opencode

Examples of how routed models appear in the picker interface.

```text
opencodex/kiro/glm-5
opencodex/gpt-5.6-sol      # native slugs stay unprefixed
```

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

### Build documentation locally

Source: https://opencodex.me/contributing

Commands to install dependencies and build the documentation site from the docs-site directory.

```bash
cd docs-site
bun install --frozen-lockfile
bun run build
```

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

### Start the OpenCodex Proxy

Source: https://opencodex.me/getting-started/quickstart

Launch the proxy on the default or a specified port.

```bash
ocx start            # defaults to port 10100
ocx start --port 8080
```

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

### Successful Service Installation Output

Source: https://opencodex.me/reference/cli/lifecycle

Confirmation message displayed when the service is successfully installed and active.

```text
✅ opencodex service installed and serving on port 10100.
```

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

### Credential Route Examples

Source: https://opencodex.me/guides/codex-app-models

Examples of model identifiers for Pool/Direct account modes versus API key transport.

```text
gpt-5.6-sol                         # openai (Pool or Direct option)
openai-apikey/gpt-5.6-sol           # API key
```

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

### Start the proxy server

Source: https://opencodex.me/reference/cli/lifecycle

Commands to launch the proxy server, optionally specifying a custom port.

```bash
ocx start
ocx start --port 8080
```

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

### Launch OpenCode with Proxy

Source: https://opencodex.me/guides/opencode

Starts the proxy and launches OpenCode with a generated provider block injected into the runtime layer.

```bash
ocx opencode
```

```bash
ocx opencode run "hello"
```

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

### Open the Web Dashboard

Source: https://opencodex.me/guides/web-dashboard

Launches the dashboard in the default browser and starts the proxy if necessary.

```bash
ocx gui
```

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

### Export Pi configuration

Source: https://opencodex.me/guides/pi

Start the proxy and generate the provider configuration block for Pi.

```bash
ocx start
ocx export --client pi
```

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

### Install with script permissions

Source: https://opencodex.me/getting-started/installation

Use these commands if npm blocks the postinstall script required for the bundled Bun runtime.

```bash
npm install -g --allow-scripts=bun @bitkyc08/opencodex


# if the original install used sudo, keep using sudo:
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex
```

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

### Define Routing and Combos

Source: https://opencodex.me/reference/configuration/routing

Example configuration showing the default provider and a combo definition with multiple targets and a failover strategy.

```json
{
  "defaultProvider": "openai",
  "combos": {
    "coding": {
      "targets": [
        { "provider": "anthropic", "model": "claude-sonnet-5" },
        { "provider": "openrouter", "model": "qwen/qwen3-coder-plus" }
      ],
      "strategy": "failover",
      "defaultEffort": "high",
      "alias": "coding-primary"
    }
  }
}
```

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

### Run Dashboard in Development Mode

Source: https://opencodex.me/guides/web-dashboard

Starts the proxy and the GUI development server separately for local development.

```bash
ocx start
bun run dev:gui
```

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

### Manage Providers and Models via CLI

Source: https://opencodex.me/reference/cli/providers-accounts

Examples of listing, testing, adding, and inspecting providers and models using the ocx command-line interface.

```bash
ocx provider list --json
ocx provider test ark
ocx provider add anthropic --api-key sk-ant-... --set-default --sync
ocx provider add local-dev --adapter openai-chat --base-url http://localhost:11434/v1
ocx provider show anthropic --json
ocx models --provider anthropic --json
ocx models live --provider ark --json
```

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

### Start the OpenCodex Proxy

Source: https://opencodex.me/getting-started/for-agents

Choose between running the proxy in the foreground or as a background service.

```bash
# Foreground: blocks this terminal until stopped.
ocx start


# Background: installs or updates the service, then starts it.
ocx service
```

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

### GET /api/settings

Source: https://opencodex.me/guides/web-dashboard

Read the current system settings.

```APIDOC
## GET /api/settings

### Description
Read the current system settings.

### Method
GET

### Endpoint
/api/settings
```

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

### Model Alias Examples

Source: https://opencodex.me/guides/claude-code

Examples of model alias formats used across different Claude interfaces.

```text
claude-ocx-native--gpt-5.6-sol
```

```text
claude-opus-4-8-ncb
```

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

### Export client configurations

Source: https://opencodex.me/reference/cli/agents

Examples of exporting client configurations for opencode and Pi, including options for JSON output and file redirection.

```bash
ocx export --client opencode                     # config plus destination, merge warning, and counts
ocx export --client pi --json > pi-models.json   # byte-exact JSON for a pipe or a diff
ocx export --client opencode --out ~/opencodex-opencode.json
```

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

### Explicit Provider/Model Routing Examples

Source: https://opencodex.me/guides/model-routing

Demonstrates the syntax for explicitly routing a model to a specific provider using the provider/model format.

```text
anthropic/claude-opus-5     →  provider "anthropic",   model "claude-opus-5"
ollama-cloud/glm-5.2        →  provider "ollama-cloud", model "glm-5.2"
openrouter/openai/gpt-5.6-sol → provider "openrouter",  model "openai/gpt-5.6-sol"
```

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

### Common Model Management Commands

Source: https://opencodex.me/reference/cli/providers-accounts

Examples of listing, toggling visibility, and configuring custom models using the ocx models CLI.

```bash
ocx models live --json                                  # what Codex can actually see right now
ocx models disable anthropic/claude-haiku-4             # hide one routed model
ocx models enable gpt-5.6-sol                           # no slash, so it is treated as native
ocx models provider zenmux off                          # hide a noisy provider wholesale
ocx models selected anthropic --set claude-opus-5,claude-fable-5
ocx models selected anthropic --clear                   # drop the allowlist again
ocx models add deepseek deepseek-v4 --display-name 'DeepSeek V4' --context-window 128000 --modalities text,image
ocx models list-custom --json                           # read the custom-id for edit/remove
ocx models remove deepseek/deepseek-v4 --yes
```

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

### Complete Provider Configuration Example

Source: https://opencodex.me/reference/configuration/providers

Defines the structure for configuring multiple AI providers, including authentication modes, base URLs, and specific sidecar settings.

```json
{
  "port": 10100,
  "defaultProvider": "openai",
  "providers": {
    "openai": {
      "adapter": "openai-responses",
      "baseUrl": "https://chatgpt.com/backend-api/codex",
      "authMode": "forward"
    },
    "anthropic": {
      "adapter": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "authMode": "oauth",
      "defaultModel": "claude-sonnet-4-6"
    },
    "ollama-cloud": {
      "adapter": "openai-chat",
      "baseUrl": "https://ollama.com/v1",
      "apiKey": "${OLLAMA_API_KEY}",
      "defaultModel": "glm-5.2",
      "noVisionModels": ["glm-5.2", "gpt-oss", "qwen3-coder", "deepseek-v4-pro"]
    }
  },
  "subagentModels": ["anthropic/claude-opus-5", "ollama-cloud/glm-5.2"],
  "disabledModels": [],
  "websockets": false,
  "webSearchSidecar": {
    "maxSearchesPerTurn": 3,
    "routedModelStallTimeoutMs": 200000,
    "timeoutMs": 60000
  },
  "visionSidecar": { "enabled": true }
}
```

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

### Configure API Settings

Source: https://opencodex.me/guides/sub-agent-surface

Example PUT requests to update surface mode and injection model settings via the management API.

```bash
curl -X PUT http://localhost:10100/api/v2 \
  -H 'Content-Type: application/json' \
  -d '{"multiAgentMode":"v2"}'


curl -X PUT http://localhost:10100/api/injection-model \
  -H 'Content-Type: application/json' \
  -d '{"model":"anthropic/claude-sonnet-5","effort":"xhigh"}'
```

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

### GET /api/startup-health

Source: https://opencodex.me/guides/web-dashboard

Read diagnostic information regarding routing, services, shims, and restart-safety.

```APIDOC
## GET /api/startup-health

### Description
Read diagnostic information regarding routing, services, shims, and restart-safety.

### Method
GET

### Endpoint
/api/startup-health
```

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

### Configure Cursor Provider

Source: https://opencodex.me/reference/configuration/providers

Example JSON configuration for the Cursor provider, to be placed within the providers object.

```json
{
  "providers": {
    "cursor": {
      "adapter": "cursor",
      "baseUrl": "https://api2.cursor.sh",
      "authMode": "oauth",
      "defaultModel": "auto",
      "nativeLocalExec": "off"
    }
  }
}
```

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

### Provider Context Capabilities Configuration

Source: https://opencodex.me/guides/model-routing

Example configuration for setting provider-specific context caps within the Codex environment.

```json
{
  "contextCapValue": 350000,
  "providerContextCaps": {
    "anthropic": 350000,
    "cursor": 350000
  }
}
```

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

### Manage Codex Shim Lifecycle

Source: https://opencodex.me/reference/cli/lifecycle

Commands to install, check the status of, or remove the lightweight codex-shim launcher.

```bash
ocx codex-shim install
ocx codex-shim status
ocx codex-shim uninstall
```

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

### Service Installation Failure Warning

Source: https://opencodex.me/reference/cli/lifecycle

Warning message displayed when the service is registered but fails to bind to the expected port.

```text
⚠️  Service installed, but no proxy answered on port 10100 within 20s.
   The manager registered the job; that is not the same as serving.
   Log:       ~/.opencodex/service.log
   Meanwhile: ocx start   (serves in the foreground)
```

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

### ocx tray <install|start|stop|status|uninstall|remove>

Source: https://opencodex.me/reference/cli/lifecycle

Controls the Windows status tray icon for managing the proxy, including installation and lifecycle management.

```APIDOC
## ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]

### Description
Installs and controls the Windows status tray icon, which provides one-click proxy controls and starts at Windows login.

### Options
- **--json**: Output status in JSON format.
- **--no-start**: Prevents the tray from launching immediately upon installation.

### Subcommands
- **install**: Install the tray icon.
- **start**: Start the tray icon.
- **stop**: Stop the tray icon.
- **status**: Report the tray icon status.
- **uninstall**: Remove the tray icon.
- **remove**: Alias of uninstall.
```

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

### Add API Key via CLI

Source: https://opencodex.me/reference/cli/providers-accounts

Examples of adding an API key using piped input or a secret manager.

```bash
ocx account add-key openrouter --label personal <<< "$OPENROUTER_API_KEY"
security find-generic-password -w openrouter | ocx account add-key openrouter --json
```

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

### Define a model combo configuration

Source: https://opencodex.me/guides/combos

Example of a top-level combos object defining a balanced strategy with multiple targets.

```json
{
  "combos": {
    "balanced": {
      "targets": [
        { "provider": "anthropic", "model": "claude-opus-4-8", "weight": 2 },
        { "provider": "openai", "model": "gpt-5.6-sol", "weight": 1 }
      ],
      "strategy": "round-robin",
      "stickyLimit": 2,
      "defaultEffort": "high",
      "alias": "team/balanced"
    }
  }
}
```

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

### GET /api/catalog

Source: https://opencodex.me/reference/management-api

Return the installed Codex catalog document.

```APIDOC
## GET /api/catalog

### Description
Return the installed Codex catalog document.

### Method
GET

### Endpoint
/api/catalog
```

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

### Alias Grammar Example

Source: https://opencodex.me/guides/claude-code

Example of a v2 alias conversion for a model ID containing special characters.

```text
openrouter/anthropic/claude-opus-4-8 → claude-ocx2-openrouter--anthropic~sclaude-opus-4-8
```

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

### Configuration, Startup, Sync, and Updates

Source: https://opencodex.me/reference/management-api

Endpoints for system configuration, service health, synchronization, and update management.

```APIDOC
## GET /api/config

### Description
Return the redacted, management-safe configuration DTO.

### Method
GET

### Endpoint
/api/config

## GET, PUT /api/settings

### Description
Read runtime/startup settings or update auto-start, stream mode, and app-owned memory budget.

### Method
GET, PUT

### Endpoint
/api/settings

## GET /api/startup-health

### Description
Read cached service/shim startup health.

### Method
GET

### Endpoint
/api/startup-health

## POST /api/startup-action

### Description
Install or repair the service or Codex shim.

### Method
POST

### Endpoint
/api/startup-action

## GET, POST /api/windows-tray

### Description
Read Windows tray state or install/start/stop/uninstall it.

### Method
GET, POST

### Endpoint
/api/windows-tray

## GET /api/diagnostics/project-config

### Description
Read cached project configuration warnings.

### Method
GET

### Endpoint
/api/diagnostics/project-config

## POST /api/sync

### Description
Sync the current model catalog into Codex.

### Method
POST

### Endpoint
/api/sync

## GET /api/update/check

### Description
Check the latest or preview update channel.

### Method
GET

### Endpoint
/api/update/check

## POST /api/update/run

### Description
Start an update job, optionally followed by restart.

### Method
POST

### Endpoint
/api/update/run

## GET /api/update/status

### Description
Poll an update job by id.

### Method
GET

### Endpoint
/api/update/status

## GET, PUT /api/sidecar-settings

### Description
Read or update web-search and vision sidecar model/backend settings.

### Method
GET, PUT

### Endpoint
/api/sidecar-settings

## GET, PUT /api/shadow-call-settings

### Description
Read or update shadow-call interception settings.

### Method
GET, PUT

### Endpoint
/api/shadow-call-settings
```

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

### GET /v1/models

Source: https://opencodex.me/reference/proxy-formats

Endpoint for model discovery.

```APIDOC
## GET /v1/models

### Description
Retrieves the available model catalog.

### Method
GET

### Endpoint
/v1/models
```

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

### GET /api/codex-auth/login-status

Source: https://opencodex.me/reference/management-api

Poll login status.

```APIDOC
## GET /api/codex-auth/login-status

### Description
Poll the status of a login flow or the current account login state.

### Method
GET

### Endpoint
/api/codex-auth/login-status
```

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

### GET /api/codex-auth/reset-credits

Source: https://opencodex.me/reference/management-api

Inspect reset-credit eligibility.

```APIDOC
## GET /api/codex-auth/reset-credits

### Description
Check if an account is eligible for reset credits.

### Method
GET

### Endpoint
/api/codex-auth/reset-credits
```

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

### GET /api/codex-auth/quota

Source: https://opencodex.me/reference/management-api

Read cached quota state.

```APIDOC
## GET /api/codex-auth/quota

### Description
Retrieve the cached quota state for a specific account.

### Method
GET

### Endpoint
/api/codex-auth/quota
```

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

### GET, PUT /api/codex-auth/active

Source: https://opencodex.me/reference/management-api

Read or select the active account.

```APIDOC
## GET, PUT /api/codex-auth/active

### Description
Retrieve the currently active account or select a new active account.

### Method
GET, PUT

### Endpoint
/api/codex-auth/active
```

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

### GET /api/usage

Source: https://opencodex.me/reference/management-api

Summarize usage by range and client surface.

```APIDOC
## GET /api/usage

### Description
Summarize usage by range and client surface.

### Method
GET

### Endpoint
/api/usage
```

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

### GET /api/logs

Source: https://opencodex.me/reference/management-api

Query filtered in-memory request logs.

```APIDOC
## GET /api/logs

### Description
Query filtered in-memory request logs.

### Method
GET

### Endpoint
/api/logs
```

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

### GET /api/claude/inbound-debug

Source: https://opencodex.me/guides/claude-code

Retrieves the latest inbound debug entries.

```APIDOC
## GET /api/claude/inbound-debug

### Description
Returns the latest inbound debug entries, limited to a ring of 20 entries.

### Method
GET

### Endpoint
/api/claude/inbound-debug

### Response
#### Success Response (200)
- **enabled** (boolean) - Status of debug capture.
- **entries** (array) - List of debug entries.
```

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

### GET /api/claude-code

Source: https://opencodex.me/guides/claude-code

Retrieves effective defaults and configuration for Claude Code.

```APIDOC
## GET /api/claude-code

### Description
Returns effective defaults, configuration, context-window registry, effective environment, available route IDs, aliases, and port.

### Method
GET

### Endpoint
/api/claude-code
```

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

### Login to Providers

Source: https://opencodex.me/reference/cli/providers-accounts

Initiate the login flow for specific providers like xAI or Anthropic.

```bash
ocx login xai
ocx login anthropic
```

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

### GET /api/logs

Source: https://opencodex.me/guides/web-dashboard

Read recent request metadata with optional filtering and pagination.

```APIDOC
## GET /api/logs

### Description
Read recent request metadata with optional tail, provider, and status filters.

### Method
GET

### Endpoint
/api/logs

### Parameters
#### Query Parameters
- **tail** (integer) - Optional - Number of lines to tail
- **limit** (integer) - Optional - Max rows to return
- **offset** (integer) - Optional - Pagination offset
- **provider** (string) - Optional - Filter by provider
- **status** (string) - Optional - Filter by status code or class (e.g., 5xx)

### Response
#### Success Response (200)
- **timeZone** (string) - Server timezone
- **total** (integer) - Total filtered row count
- **logs** (array) - List of log entries
```

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

### Service Status Report

Source: https://opencodex.me/reference/cli/lifecycle

Diagnostic output showing the service is correctly installed and serving.

```text
✅ installed and loaded (launchd; logs: …)
   Serving on port 10100.
```

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

### List configured combos via CLI

Source: https://opencodex.me/guides/combos

Command to verify the list of available combos when troubleshooting 404 errors.

```bash
ocx combo list
```

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

### ocx codex-shim <install|status|uninstall|remove>

Source: https://opencodex.me/reference/cli/lifecycle

Manages the codex-shim launcher on the system PATH to enable lightweight, on-demand startup of the Codex proxy.

```APIDOC
## ocx codex-shim <install|status|uninstall|remove>

### Description
Wraps a script-based codex launcher on PATH with a lightweight autostart script. This allows the proxy to start only when codex is launched.

### Subcommands
- **install**: Install the shim or repair it if stale.
- **status**: Report the current shim state (installed, stale, or missing).
- **uninstall**: Remove the shim and restore the original Codex binary.
- **remove**: Alias of uninstall.

### Usage Example
```bash
ocx codex-shim install
ocx codex-shim status
ocx codex-shim uninstall
```
```

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

### Account Management Help

Source: https://opencodex.me/reference/cli/providers-accounts

Displays the available subcommands for managing accounts and API keys.

```bash
Usage: ocx account <list|current|use|refresh|auto-switch|login|reauth|code|cancel|remove|add-key|reset-credits> ...


list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).
current <provider>  Show the active account or key.
use <provider> <id> Switch the active credential; 'main' selects the Codex App login.
refresh <provider>  Force-refresh Codex or provider quota reports.
auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.
remove <provider> <id> --yes  Remove a stored account or key after an existence check.
add-key <provider> [--label <label>]  Add a key read only from piped stdin.
login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.
reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.
Codex pool selection applies to the next request after clearing existing affinity; in-flight requests keep their captured account.
```

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

### GET, POST, DELETE /api/codex-auth/accounts

Source: https://opencodex.me/reference/management-api

List, refresh, import, or delete Codex accounts.

```APIDOC
## GET, POST, DELETE /api/codex-auth/accounts

### Description
List or refresh accounts, optionally import new accounts, or delete existing Codex accounts.

### Method
GET, POST, DELETE

### Endpoint
/api/codex-auth/accounts
```

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

### Configure system settings

Source: https://opencodex.me/reference/cli/agents

Sets the runtime stream mode to eager-relay for the system configuration.

```bash
ocx system settings --stream-mode eager-relay
```

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

### Create a combo

Source: https://opencodex.me/guides/combos

Define a new combo with a list of prioritized provider/model targets.

```bash
ocx combo set main --targets anthropic/claude-opus-4-8,openai/gpt-5.6-sol
```

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

### GET, PUT /api/debug

Source: https://opencodex.me/reference/management-api

Read debug flags or set, clear, or reset capture categories.

```APIDOC
## GET, PUT /api/debug

### Description
Read debug flags; set, clear, or reset capture categories.

### Method
GET, PUT

### Endpoint
/api/debug
```

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

### Create an API key for deployment

Source: https://opencodex.me/reference/cli/agents

Creates a new API key specifically for deployment purposes.

```bash
ocx access key create deployment
```

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

### Selecting models in Grok Build

Source: https://opencodex.me/guides/grok-build

Commands to list available models and execute prompts using the registered opencodex models.

```bash

grok models          # lists ocx-* entries alongside native grok models
grok -m ocx-anthropic-claude-opus-4-8 -p "hello"
# or in the TUI: /model ocx-anthropic-claude-opus-4-8

```

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

### Show combo configuration

Source: https://opencodex.me/guides/combos

Retrieve the saved definition of a specific combo.

```bash
ocx combo show main
```

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

### Configure Remote Access Authentication

Source: https://opencodex.me/getting-started/for-agents

Sets the required API token for non-loopback binds before installing the service.

```bash
export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
ocx service install
```

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

### Add a Provider

Source: https://opencodex.me/getting-started/for-agents

Registers a new provider using an API key and sets it as the default.

```bash
ocx provider add anthropic-apikey \
  --api-key "$ANTHROPIC_API_KEY" \
  --set-default
```

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

### Execute Build and Test Commands

Source: https://opencodex.me/contributing

Standardized commands for type checking, testing, building the GUI, and running CI-related scans.

```bash
bun run typecheck                 # strict TypeScript check
bun run test                      # complete tests/ suite
bun test tests/router.test.ts     # focused test file
bun run build:gui                 # Vite GUI build + package preparation
bun run privacy:scan              # credential/privacy scan used by CI
bun run prepare:package           # refresh package launchers/assets
```

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

### ocx service [install|start|stop|status|uninstall|remove]

Source: https://opencodex.me/reference/cli/lifecycle

Manages the OpenCodex background service lifecycle. This command interacts with system-level service managers (launchd, systemd, or Task Scheduler) to ensure the proxy runs as a background process.

```APIDOC
## ocx service [subcommand]

### Description
Manages the OpenCodex background service. Running the command without a subcommand creates or updates and starts the service.

### Subcommands
- **install**: Create and start the service.
- **start**: Start an installed service.
- **stop**: Stop the service and restore native Codex.
- **status**: Report service and proxy diagnostics plus log paths.
- **uninstall**: Remove the service and restore native Codex.
- **remove**: Alias of uninstall.

### Usage Examples
```bash
ocx service
ocx service install
ocx service status
ocx service uninstall
```
```

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

### Configure Round-Robin Combo

Source: https://opencodex.me/guides/combos

Sets up a balanced combo using the round-robin strategy with specific weights and a sticky limit for request persistence.

```bash
ocx combo set balanced \
  --targets anthropic/claude-opus-4-8:2,openai/gpt-5.6-sol:1 \
  --strategy round-robin \
  --sticky 2
```

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

### Execute release helper commands

Source: https://opencodex.me/contributing

Commands for managing project releases, including version bumping, publishing, and monitoring workflow status.

```bash
bun run release <version>           # commits/pushes the bump; publish workflow is dry-run by default
bun run release <version> --publish # publish after the CI-gated dry run is understood
bun run release:watch               # watch the newest Release workflow run
```
Tokens:
Raw