How to add Nous Research as a provider in nanobot

[Metrium987]

How to add Nous Research as a provider in nanobot

This guide explains how to point nanobot at the Nous Research Inference API (https://inference-api.nousresearch.com/v1) so you can use models like tencent/hy3:free directly from nanobot.

All steps below were verified live against nanobot-ai==0.2.2 and the Nous Portal inference endpoint. The one non-obvious requirement (the user tag) is explained in the "Important gotcha" section — it is not in the official Nous API docs and was found by reading error messages.

---

1. Prerequisites

• nanobot installed (any 0.2.x). Install it with:

  uv tool install nanobot-ai

  Verify:

  nanobot --version

• A Nous Research API key. Generate one at https://portal.nousresearch.com (API keys section). The key looks like sk-nous-xxxxxxxx.

Note: the Nous Portal inference endpoint accepts OpenAI-compatible keys. The same sk-nous-... key also works against OpenRouter (https://openrouter.ai/api/v1); the two endpoints apply different rate limits, so pick the endpoint that matches the model you want.

---

2. Configure the provider

Open your nanobot config file:

~/.nanobot/config.json

Fill in the providers.custom block with your key and the Nous base URL. nanobot treats custom as "any OpenAI-compatible endpoint," which is exactly what Nous Portal is.

"providers": {
  "custom": {
    "apiKey": "sk-nous-YOUR_KEY_HERE",
    "apiBase": "https://inference-api.nousresearch.com/v1",
    "apiType": "auto",
    "extraHeaders": null,
    "extraBody": {
      "tags": [
        "user=nanobot"
      ]
    },
    "extraQuery": null
  },
  ...
}

Important gotcha — the user tag

The Nous Portal /chat/completions route requires a user tag in the request, even though it is not documented in the official OpenAPI spec (https://portal.nousresearch.com/api/openapi, which only lists model, messages, temperature, max_tokens, stream).

If you omit it, the API returns:

{"status":400,"message":"This request is not valid. Check the model name and other parameters. Additional info: missing tags"}

and if you send tags without a user= entry, it returns:

{"status":400,"message":"... Additional info: missing user tag"}

The working shape is a tags array containing one entry whose key is user:

"tags": ["user=nanobot"]

The user value is free-form (e.g. user=nanobot, user=my-agent). What matters is the user= key prefix. nanobot sends extraBody and the OpenAI-compatible SDK flattens extraBody into the request root, so the server sees tags at the top level where it expects it.

Why is this undocumented? The officially supported path is OAuth login (what Hermes Agent does). With OAuth, your user identity travels inside the bearer token, so no user tag is needed. With a raw API key, the server cannot infer your identity and asks for it explicitly via the user tag. Because raw-key usage is not the documented path, the tag is absent from the public spec. Treat it as stable-but-unsupported: it works today, but Nous could change the validation without notice.

The Hermes Agent reference implementation (agent/portal_tags.py) only ever sends product=hermes-agent / client=hermes-client-v<ver> / conversation=<id> tags — never a user= tag — because it authenticates over OAuth. The user= requirement is specific to raw API-key callers.

---

3. Create a model preset

Add a preset under model_presets so you can switch models and pin the default:

"model_presets": {
  "primary": {
    "label": "Primary",
    "provider": "custom",
    "model": "tencent/hy3:free",
    "maxTokens": 8192,
    "contextWindowTokens": 200000,
    "temperature": 0.1
  }
}

Then activate it by setting the default preset:

"agents": {
  "defaults": {
    "modelPreset": "primary",
    ...
  }
}

Field names: nanobot's config accepts both camelCase (modelPreset, maxTokens, contextWindowTokens) and snake_case (model_preset, max_tokens, context_window_tokens). The examples above use the camelCase form that the onboarding wizard writes.

---

4. Verify

Check that nanobot reads the config correctly:

nanobot status

You should see:

Model: tencent/hy3:free (preset: primary)
Custom: ✓

Then run a real chat to confirm the endpoint accepts the request (including the user tag):

nanobot agent

or a one-shot message. If you get a 400 missing user tag, double-check that extraBody.tags contains a user=... entry (step 2).

---

5. Rate limits

When you call https://inference-api.nousresearch.com/v1, you are subject to Nous Portal rate limits (from the official API docs):

• Free tier: 50 RPM / 500,000 TPM

If you instead point apiBase at OpenRouter and use the same sk-nous-... key, you are subject to OpenRouter free-tier limits instead (≈ 20 RPM / 200 requests per day for :free models). The endpoint you choose, not the key, decides the limit.

---

6. Minimal working config.json snippets (copy-paste)

Provider block:

"providers": {
  "custom": {
    "apiKey": "sk-nous-YOUR_KEY_HERE",
    "apiBase": "https://inference-api.nousresearch.com/v1",
    "apiType": "auto",
    "extraHeaders": null,
    "extraBody": { "tags": ["user=nanobot"] },
    "extraQuery": null
  }
}

Preset + activation:

"model_presets": {
  "primary": {
    "label": "Primary",
    "provider": "custom",
    "model": "tencent/hy3:free",
    "maxTokens": 8192,
    "contextWindowTokens": 200000,
    "temperature": 0.1
  }
},
"agents": {
  "defaults": { "modelPreset": "primary" }
}

---

Troubleshooting

Symptom	Cause	Fix
400 missing tags	tags not sent	Add "extraBody": {"tags": ["user=nanobot"]} to providers.custom
400 missing user tag	tags present but no user= entry	Use "tags": ["user=nanobot"] (the user= key is required)
404 ... requires available credits	You used a paid model id (e.g. tencent/hy3 without :free) on a free account	Use the :free variant, or add credits at portal.nousresearch.com
404 Model 'tencent/hy3:free' requires available credits	Account has no credits for that model	Use a free model, or top up
nanobot: command not found	uv's bin dir not on PATH	Run via uv tool run --from nanobot-ai nanobot ..., or add ~/.local/bin to PATH

---

Sources

• nanobot install & config: https://github.com/HKUDS/nanobot (README "Install" / "Quick Start" / "Configuration")
• Nous Portal API base URL & docs: https://portal.nousresearch.com/api-docs, OpenAPI spec: https://portal.nousresearch.com/api/openapi
• Hermes Agent portal_tags.py (tag shape reference): https://github.com/NousResearch/hermes-agent — agent/portal_tags.py
• Model tencent/hy3:free is served by Nous Portal (verified live: GET /v1/models lists tencent/hy3:free with synthesizedFreeVariant: true).

[Ziuluiziul]

Nice write-up — this matches what I see against the live Nous endpoint.

One practical tip when wiring nanobot (or any OpenAI client) to https://inference-api.nousresearch.com/v1: after the first chat completion on a :free model, check the response x-ratelimit-* headers. Free tier is documented as 50 RPM / 500k TPM, and a tiny smoke usually leaves remaining around 49/50 req and nearly full token budget if nothing else is burning quota.

I published a minimal smoke + cotas report (model used, HTTP status, usage, remaining headers) here in case it helps others validate their key/config before debugging nanobot provider settings: https://gist.github.com/Ziuluiziul/296fa307f82eb950e49cb54af08301eb

Also note Hermes returns 404 on that free path in my checks — stick to the :free catalog models that actually answer 200.