nanobot

Connect nanobot to CoffeeRouter with a custom provider and model preset in config.json.

Before you begin

  • Install Python 3.11 or later.
  • Create an active CoffeeRouter token and note the exact model IDs available to it.
  • The CoffeeRouter OpenAI-compatible base URL is https://www.coffeerouter.ai/v1.

Configuration steps

1. Install and initialize nanobot

On macOS or Linux, run the official installer:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

On Windows PowerShell, run:

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

You can also install nanobot with uv or pip:

uv tool install nanobot-ai

python -m pip install nanobot-ai

Then start the guided setup:

nanobot onboard --wizard

2. Set the CoffeeRouter token

Use an environment variable for the token. On macOS, Linux, or WSL:

export COFFEEROUTER_API_KEY="sk-your-api-key"

On Windows PowerShell:

$env:COFFEEROUTER_API_KEY = "sk-your-api-key"

If nanobot runs as a background service, set the variable persistently in that service's environment instead of only in the current terminal.

3. Add the CoffeeRouter provider and model preset

Open ~/.nanobot/config.json; on Windows, the equivalent path is %USERPROFILE%\.nanobot\config.json. Merge the following fields into the configuration generated by the wizard. Keep any existing channel and tool settings:

{
    "providers": {
        "coffeerouter": {
            "apiKey": "${COFFEEROUTER_API_KEY}",
            "apiBase": "https://www.coffeerouter.ai/v1"
        }
    },
    "modelPresets": {
        "coffeerouter-main": {
            "label": "CoffeeRouter",
            "provider": "coffeerouter",
            "model": "your-model-id"
        }
    },
    "agents": {
        "defaults": {
            "modelPreset": "coffeerouter-main"
        }
    }
}

Replace your-model-id with the complete model ID available to your CoffeeRouter token. nanobot resolves ${COFFEEROUTER_API_KEY} from the environment at startup and does not write the resolved secret back to the file.

Verify the connection

Check the configuration status:

nanobot status

Then send a test message:

nanobot agent -m "Reply with: CoffeeRouter connected"

For an interactive session, run:

nanobot agent

Troubleshooting

Why is the nanobot command not found?

Reopen the terminal and run the PATH command printed by the installer. With uv, you can first verify the installation with uv tool run --from nanobot-ai nanobot --version. Do not assume every platform uses the same .local/bin path.

Why do requests return 401 or an invalid API key error?

Confirm that the current process can read COFFEEROUTER_API_KEY, and that the token is complete, enabled, unexpired, and has available quota. Configure the environment separately for a background service.

Why is the model not found?

The model in modelPresets must exactly match a model ID shown in CoffeeRouter, and the current token must be allowed to use it.

Can I put the key directly in the configuration file?

apiKey accepts a literal key, but ${COFFEEROUTER_API_KEY} is safer because it keeps the secret out of backups, source control, and configuration screenshots.

Security

Do not share config.json, tokens, terminal screenshots, or logs containing request headers. Create a dedicated nanobot token with model, quota, and IP restrictions, and revoke it when it is no longer needed.

Official resources