opencode-nim-rotator

An OpenCode plugin for managing and rotating multiple NVIDIA NIM API keys.

How It Works

The plugin hooks into OpenCode's chat.headers pipeline to inject a rotated API key into the Authorization header on every outgoing NVIDIA NIM API request. It also hooks shell.env so NVIDIA API keys are rotated for shell commands too.

Key rotation happens per-request: each LLM call uses the next key in the rotation. If a key returns 401, 403, or 429, it automatically increments the failure count and retries with the next key.

Install

npm install -g opencode-nim-rotator

The postinstall script automatically adds the plugin to your ~/.config/opencode/opencode.json.

Setup

1. Add API keys

Run the TUI manager:

opencode-nim-rotator

Or manually — add at least one key via OpenCode's auth system:

opencode /connect nvidia

Select "Enter NVIDIA NIM API Key" and paste your key.

2. Add more keys via the TUI

opencode-nim-rotator

The TUI lets you:

• Add keys with a friendly name
• Rename keys
• Delete keys
• Toggle keys on/off
• Reset failure counts
• Switch rotation strategy (round-robin or least-failures)
• Export keys to a JSON file
• Import keys from a JSON file

3. Restart OpenCode

After adding keys, restart opencode. The plugin's chat.headers hook will rotate keys on every NVIDIA API request.

Configuration

Environment Variables

| Variable | Description | Default | | -------------------------- | ----------------------------------- | ------------------------------------------ | | NIM_ROTATOR_STORE_PATH | Path to key store JSON file | ~/.config/opencode/nim-rotator-keys.json | | NIM_ROTATOR_MAX_FAILURES | Max failures before disabling a key | 5 | | NVIDIA_API_KEY | Fallback API key (auto-seeded) | — |

opencode.json Options

{
  "plugin": [
    [
      "opencode-nim-rotator",
      {
        "rotationStrategy": "round-robin",
        "storePath": "/custom/path/to/keys.json"
      }
    ]
  ]
}

Rotation Strategies

• round-robin (default): Cycles through keys in order
• least-failures: Always uses the key with the fewest failures

How Key Rotation Works

1. On startup, the plugin loads the key store
2. Every NVIDIA API call goes through the chat.headers hook
3. The hook selects the next key based on the rotation strategy
4. The Authorization: Bearer <key> header is replaced with the rotated key
5. If the request returns 401, 403, or 429, the failure count is incremented and the next key is tried
6. Keys that exceed NIM_ROTATOR_MAX_FAILURES are automatically skipped
7. Successful requests reset the key's failure count to 0

Key Store Format

Keys are stored in ~/.config/opencode/nim-rotator-keys.json with file mode 0600:

{
  "keys": [
    {
      "id": "uuid",
      "name": "work-key",
      "key": "nvapi-...",
      "createdAt": 1700000000000,
      "lastUsedAt": 1700000100000,
      "failureCount": 0,
      "enabled": true
    }
  ],
  "currentIndex": 0,
  "rotationStrategy": "round-robin",
  "updatedAt": 1700000000000,
  "lastUsedKeyId": "uuid"
}

Themes

The TUI supports multiple color themes that match OpenCode's built-in themes. By default, the rotator syncs with your opencode.json theme setting — when you change your theme in OpenCode, the rotator picks it up automatically.

Available Themes

| ID | Name | | ------------ | ------------------ | | opencode | OpenCode (default) | | catppuccin | Catppuccin Mocha | | dracula | Dracula | | gruvbox | Gruvbox | | kanagawa | Kanagawa | | nord | Nord | | one-dark | One Dark | | rosepine | Rose Pine | | solarized | Solarized | | tokyonight | Tokyonight |

Setting a Theme

From the TUI main menu, select Theme to pick a theme or switch back to syncing with opencode.json.

To override via opencode.json:

{
  "theme": "dracula"
}

To override independently (saved in the key store):

{
  "theme": "kanagawa",
  "keys": [...]
}

Set the store theme field to "" or remove it to revert to syncing with opencode.json.

TUI

The TUI is built with OpenTUI and provides a menu-driven interface:

• Main menu with Manage, Add, Reset Failures, Export, Import, Strategy, Theme, and Quit options
• Key selector showing name, masked key, failure count, last used
• Key actions: toggle, rename, delete
• Add key flow: enter name, then enter key (must start with nvapi-)
• Theme selector with live preview and sync-to-opencode option
• Export keys to JSON file
• Import keys from JSON file with validation and deduplication

Development

# Install dependencies
bun install

# Run TUI locally
bun run tui

# Build TypeScript
bun run build

Uninstall

To remove the plugin and clean up all associated data:

npm uninstall -g opencode-nim-rotator

The uninstaller will automatically:

1. Remove opencode-nim-rotator from your ~/.config/opencode/opencode.json plugin list
2. Delete your key store file at ~/.config/opencode/nim-rotator-keys.json

Note: This will permanently delete all stored API keys, so back them up first if needed. After uninstalling, restart opencode to apply the changes.

License

MIT