hamro.site — Free AI Gateway · Full Documentation

A single, OpenAI-compatible API that gives you free access to multiple frontier models through one key and one URL. It aggregates ten providers — Groq, OpenRouter, OpenCode Zen, Ollama Cloud, Naga AI, ZenMux, LLM7, Cerebras, Chutes and HuggingFace — into a smart routing layer with automatic failover, so coding agents (Claude Code, Cursor, Aider, OpenCode, custom CLIs) never see a broken connection.

bash copy
Your agent / script
        │  OpenAI-compatible calls, one key
        ▼
  ┌───────────────────┐
  │  hamro.site       │   /v1/chat/completions, /v1/models
  │  smart router     │   sticky success + auto-failover
  │  random mode      │   model: "random" → pinned per session
  └─────────┬─────────┘
            │
   ┌────────┼────────────┬──────────┬───────────┬───────────┐
   ▼        ▼            ▼          ▼           ▼           ▼
 Groq    OpenRouter  OpenCode   Ollama     Naga AI    HuggingFace
(llama) (nemotron)  (deepseek) (nemotron)  (nemotron)  (llama, deepseek)
 + ZenMux · LLM7 · Cerebras · Chutes

Table of contents

1. The free models
2. Quick start — 2 minutes
3. API reference
   • Authentication
   • POST /v1/chat/completions
   • Streaming (SSE)
   • GET /v1/models
   • Response headers
   • Errors
   • Failover & routing
4. Using it with coding agents
   • Claude Code
   • Cursor
   • Aider
   • OpenCode / Continue / other agents
5. Getting free API keys
6. Self-hosting & deployment
7. Data, telemetry & the status page
8. Security notes
9. Troubleshooting

The free models

Nearly every model is 100% free (the router also tracks estimated cost for the paid fallback entries). The full catalog is always available from

GET /v1/models

model

groq/llama-3.3-70b-versatile

ollama/nemotron-3-ultra

ollama/gpt-oss:120b

naga/nemotron-3-ultra-550b-a55b:free

naga/nemotron-3-super-120b-a12b:free

naga/llama-3.3-70b-instruct:free

naga/llama-4-scout-17b-16e-instruct:free

llm7/gpt-oss:20b

huggingface/meta-llama/Llama-3.3-70B-Instruct

huggingface/deepseek-ai/DeepSeek-V4-Flash

huggingface/zai-org/GLM-5.2

zenmux/deepseek/deepseek-v4-flash-free

zenmux/z-ai/glm-4.7-flash-free

cerebras/zai-glm-4.7

openrouter/openrouter/free

opencode/deepseek-v4-flash-free

random

You can also pass a bare model id (

llama-3.3-70b-versatile

The canonical id is

text copy

provider/model

. Because the OpenRouter model id is itself

text copy

openrouter/free

, its canonical id is

text copy

openrouter/openrouter/free

.

Random model mode

Set

"model": "random"

"auto"

• the session goes idle past
  text copy

  RANDOM_SESSION_TTL_SECONDS

  (default 1 hour), or
• the pinned model returns an error (401/402/403/404/429/5xx, timeout, network failure) — the request then fails over to other random models and the next request picks a fresh random one.

Sessions are identified by (API key +

x-session-id

user

X-Gateway-Session-Model

Quick start — 2 minutes

bash copy
# 1. Check the models
curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer nishan-bajagain"

# 2. Ask a question (non-streaming)
curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer nishan-bajagain" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "groq/llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "Explain monads in one sentence."}]
  }'

# 3. Stream a reply
curl -N http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer nishan-bajagain" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/deepseek-v4-flash-free",
    "messages": [{"role": "user", "content": "Write a bubble sort in Python."}],
    "stream": true
  }'

Replace

http://localhost:3000

API reference

Base URL

http://localhost:3000

https://your-domain.com

All endpoints live under

/v1

baseURL

apiKey

Authentication

Every

/v1/*

makefile copy
Authorization: Bearer nishan-bajagain

• Missing or wrong key →
  text copy

  401 {"error": {"message": "Invalid API key", ...}}

• The check is timing-safe and works for browser clients (CORS enabled).
• text copy

  GET /v1/models

  ,
  text copy

  POST /v1/chat/completions

  both require it.
• You can change the key in
  text copy

  .env

  (
  text copy

  PUBLIC_API_KEY

  ).

POST /v1/chat/completions

OpenAI-compatible chat completions with optional streaming.

Request body (all standard OpenAI fields are passed through):

jsonc copy
{
  "model": "groq/llama-3.3-70b-versatile",   // any model id from /v1/models
  "messages": [
    { "role": "system", "content": "You are a terse coding assistant." },
    { "role": "user", "content": "Refactor this function..." }
  ],
  "stream": false,          // true → SSE events (see below)
  "temperature": 0.3,       // optional
  "max_tokens": 1024,       // optional
  "top_p": 1,               // optional
  "tools": [...],           // optional — tool calling passes through verbatim
  "tool_choice": "auto",
  "stream_options": { "include_usage": true }  // optional — usage in final chunk
}

Non-streaming response (200):

jsonc copy
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1754700000,
  "model": "groq/llama-3.3-70b-versatile",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "...",
        "tool_calls": null      // present when the model calls tools
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 40,
    "total_tokens": 65
  }
}

Streaming (SSE)

Set

"stream": true

text/event-stream

kotlin copy
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

• Reasoning models (e.g. DeepSeek) stream their reasoning in
  text copy

  delta.reasoning

  /
  text copy

  delta.reasoning_content

  — pass it through if your client understands it.
• If
  text copy

  stream_options.include_usage

  is supported by the upstream provider, the final chunk before
  text copy

  [DONE]

  includes
  text copy

  usage

  .
• If an upstream provider fails mid-stream, the gateway emits an error chunk and
  text copy

  [DONE]

  so your client's stream parser never hangs.

GET /v1/models

Lists every configured, operational model:

jsonc copy
{
  "object": "list",
  "data": [
    {
      "id": "groq/llama-3.3-70b-versatile",
      "object": "model",
      "created": 1735689600,
      "owned_by": "groq",
      "context_length": 131072,
      "pricing": { "input": "0.5900", "output": "0.7900" }
    }
    // ...
  ]
}

Response headers

Every completion response carries routing telemetry:

x-gateway-provider

groq

openrouter

opencode

x-gateway-model

x-gateway-failovers

0

x-gateway-latency-ms

x-gateway-cache

HIT

MISS

x-rate-limit-limit

x-rate-limit-remaining

Errors

401

400

404

429

Retry-After

502

504

499

Error bodies follow the OpenAI shape:

{"error": {"message", "type", "code"}}

Failover & routing

The router implements sticky success:

1. Requested model → try it first (if its provider has been healthy recently).
2. On 401 / 403 / 404 / 429 / 5xx / timeout / network error, it falls back to the next entry in
   text copy

   MODEL_FALLBACK_CHAIN

   without breaking the connection (streaming fails over before the first token).
3. Providers that fail get a 30-second cooldown; providers that succeed stay prioritized.
4. Every attempt is logged;
   text copy

   /status

   shows failover events with arrows.

Chat history database (

text copy

/api/chats

)

The web client saves its chat history to the gateway's own database (

data.json

GET /api/chats

?full=1

GET /api/chats/:id

POST /api/chats

{id?, title, messages}

{chats: […]}

DELETE /api/chats/:id

DELETE /api/chats

bash copy
# Save a chat
curl http://localhost:3000/api/chats \
  -H "Authorization: Bearer nishan-bajagain" \
  -H "Content-Type: application/json" \
  -d '{"id":"chat_1","title":"Refactor","messages":[{"role":"user","content":"hi"}]}'

# List summaries
curl http://localhost:3000/api/chats -H "Authorization: Bearer nishan-bajagain"

Enforced limits (400 on violation): 50 chats per key, 200 messages per chat, 200 KB per chat, 8 KB per message, 100-char titles. Chats persist to

data.json

Rate limiting

Every API key gets a sliding-window rate limit (default 120 requests/minute). When exceeded you get

429

Retry-After

env copy
RATE_LIMIT_RPM=120     # requests per minute per key — set 0 to disable

Deterministic response cache

Identical non-streaming requests with

temperature: 0

x-gateway-cache: HIT

env copy
CACHE_TTL_SECONDS=60   # seconds a cached response lives — set 0 to disable
CACHE_MAX_ENTRIES=200  # LRU cap

Default chain (edit

MODEL_FALLBACK_CHAIN

.env

bash copy
groq/llama-3.3-70b-versatile
  → ollama/nemotron-3-ultra
  → naga/nemotron-3-ultra-550b-a55b:free
  → llm7/gpt-oss:20b
  → huggingface/meta-llama/Llama-3.3-70B-Instruct
  → openrouter/nvidia/nemotron-3-ultra-550b-a55b:free
  → zenmux/deepseek/deepseek-v4-flash-free
  → cerebras/zai-glm-4.7
  → chutes/deepseek-ai/DeepSeek-V4-Flash-0731-TEE
  → opencode/nemotron-3-ultra-free
  → opencode/deepseek-v4-flash-free

Using it with coding agents

Claude Code

The gateway speaks the Anthropic Messages protocol natively (

POST /v1/messages

/v1/messages/count_tokens

random

One command (recommended):

bash copy
cd hamro.ai
npm run claude              # starts the gateway if needed + opens Claude Code

What it does:

1. Starts the gateway on port 3000 if it isn't already running (builds it on first run, logs to
   text copy

   .freebuff/hamro-server.log

   ).
2. Writes an isolated settings file (
   text copy

   .freebuff/claude-settings.json

   ) that points Claude Code at the gateway — your global
   text copy

   ~/.claude/settings.json

   is never modified. This matters because a global settings-file
   text copy

   env

   block overrides shell environment variables.
3. Sets
   text copy

   ANTHROPIC_MODEL

   (default
   text copy

   random

   — a model is picked once per session and pinned until it errors) and
   text copy

   ANTHROPIC_SMALL_FAST_MODEL

   for background tasks.
4. Opens the Claude Code TUI.

Useful variants:

bash copy
npm run claude -- --check                    # verify gateway + config, don't open
npm run claude -- --model groq/llama-3.3-70b-versatile   # pin a specific model
npm run claude -- --restart                  # force-restart a stale gateway build
npm run claude -- --port 4000                # different port

Manual equivalent (if you don't want to use the launcher): create

~/.claude/settings.json

jsonc copy
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:3000",   // no /v1 — Claude Code appends it
    "ANTHROPIC_AUTH_TOKEN": "nishan-bajagain",       // your gateway key
    "ANTHROPIC_MODEL": "random",                     // or any model id from /v1/models
    "ANTHROPIC_SMALL_FAST_MODEL": "groq/llama-3.3-70b-versatile"
  }
}

(If you prefer a proxy instead, Claude Code Router (CCR) still works: install

npm install -g @musistudio/claude-code-router

http://localhost:3000/v1

nishan-bajagain

http://127.0.0.1:3456

Cursor

1. Cursor Settings → Models → OpenAI API Key: enter
   text copy

   nishan-bajagain

   .
2. Override OpenAI Base URL:
   text copy

   http://localhost:3000/v1

   .
3. Add the model ids (e.g.
   text copy

   groq/llama-3.3-70b-versatile

   ) and enable them.
4. Pick one in the model picker and chat.

Cursor sends OpenAI-format requests, so it works directly — no proxy needed.

Aider

bash copy
aider \
  --openai-api-base http://localhost:3000/v1 \
  --openai-api-key nishan-bajagain \
  --model openai/groq/llama-3.3-70b-versatile

Aider's model name is

text copy

openai/<id>

— the

text copy

openai/

prefix tells Aider "this is an OpenAI-compatible chat model", it does not send requests to OpenAI.

OpenCode / Continue / other agents

Anything that supports a custom OpenAI-compatible endpoint works directly:

http://localhost:3000/v1

nishan-bajagain

/v1/models

This includes OpenCode (the CLI), Continue, Roo Code, Cline, Windsurf, Zed, Raycast AI, and custom scripts.

Getting free API keys

The gateway ships with working keys, but if you deploy your own instance you need your own (all free):

llama-3.3-70b-versatile

:free

openrouter/free

nemotron-3-ultra-free

deepseek-v4-flash-free

nemotron-3-ultra

gpt-oss:120b

:free

-free

gpt-oss:20b

gemma4:31b

zai-glm-4.7

Copy them into

.env

.env.example

env copy
PUBLIC_API_KEY="nishan-bajagain"
GROQ_API_KEY="gsk_..."
OPENROUTER_API_KEY="sk-or-..."
OPENCODE_API_KEY="sk-..."
OPENCODE_BASE_URL="https://opencode.ai/zen/v1"
OLLAMA_API_KEY="..."
NAGA_API_KEY="ng-..."
ZENMUX_API_KEY="sk-mg-v1-..."
LLM7_API_KEY="..."
CEREBRAS_API_KEY="csk-..."
CHUTES_API_KEY="cpk_..."
HUGGINGFACE_API_KEY="hf_..."
MODEL_FALLBACK_CHAIN="groq/llama-3.3-70b-versatile,ollama/nemotron-3-ultra,naga/nemotron-3-ultra-550b-a55b:free,llm7/gpt-oss:20b,huggingface/meta-llama/Llama-3.3-70B-Instruct,openrouter/nvidia/nemotron-3-ultra-550b-a55b:free,zenmux/deepseek/deepseek-v4-flash-free,cerebras/zai-glm-4.7,chutes/deepseek-ai/DeepSeek-V4-Flash-0731-TEE,opencode/nemotron-3-ultra-free,opencode/deepseek-v4-flash-free"

Self-hosting & deployment

Local

bash copy
npm install
npm run dev        # http://localhost:3000
# or production:
npm run build && npm start

Vercel / Netlify / any serverless host

No database needed. The gateway stores telemetry in a JSON file (

data.json

bash copy
vercel
# set the env vars above in the Vercel dashboard (or `vercel env add`)

To keep

/status

Option 1 — free remote JSON (zero setup). The gateway auto-creates a free jsonblob.com blob on first write, remembers its URL in

data.json

env copy
# optional — durable endpoint you control (any JSON service speaking GET/PUT):
# REMOTE_JSON_URL="https://jsonblob.com/api/jsonBlob/<id>"

Paste a

https://jsonblob.com/<id>

REMOTE_JSON_URL

Option 2 — Vercel KV / Upstash. Add a free Vercel KV / Upstash Redis store and set its two env vars. The gateway persists telemetry to the shared KV (via plain

fetch

env copy
KV_REST_API_URL="https://your-kv.upstash.io"
KV_REST_API_TOKEN="AUpX..."

Without any of the above:

• Set
  text copy

  DATA_FILE

  to a writable absolute path if you have a mounted volume (e.g.
  text copy

  /data/hamro-data.json

  ) to persist telemetry across cold starts.
• Otherwise
  text copy

  /status

  still works — data just resets when the instance recycles (Vercel's
  text copy

  /tmp

  is per-instance and ephemeral).

OpenCode Zen and free OpenRouter models can be slow on first token (5–20 s). Raise your platform's function timeout if you see

504

VPS / Docker-friendly hosts

data.json

Data, telemetry & the status page

• text copy

  /status

  — live dashboard: provider health grid, aggregate + per-model usage (requests, prompt/completion tokens, estimated cost, avg latency), color-coded event log with failover arrows. Auto-refreshes health checks.
• text copy

  /api/status

  — the same data as JSON.
• text copy

  POST /api/healthcheck

  — pings every provider and updates status.
• text copy

  GET /api/health

  — lightweight unauthenticated probe (provider status, uptime, request count) for uptime monitors and Vercel Cron;
  text copy

  200

  when all providers are online,
  text copy

  503

  when degraded.
• text copy

  data.json

  — all request logs + provider status (max 5,000 recent records; oldest pruned) plus the chat-history database (
  text copy

  chats

  section, namespaced per key). Plain JSON, no database engine.

Storage resolution order: shared KV (

KV_REST_API_URL

KV_REST_API_TOKEN

DATA_FILE

./data.json

/tmp/hamro-data.json

Security notes

• text copy

  nishan-bajagain

  is the public shared key — anyone with it can use your gateway. Change
  text copy

  PUBLIC_API_KEY

  in
  text copy

  .env

  if you want to restrict access, and treat anything pasted into chat/forums as compromised (rotate provider keys too if they were shared publicly).
• text copy

  .env

  is gitignored. Never commit provider keys.
• CORS is wide open (
  text copy

  *

  ) on
  text copy

  /v1/*

  so browser-based agents work. Lock it down in
  text copy

  next.config.ts

  if you deploy publicly.

Troubleshooting

401 Invalid API key

Authorization: Bearer <PUBLIC_API_KEY>

429

x-gateway-failovers

502 All providers failed

.env

POST /api/healthcheck

/status

429 rate limit exceeded

RATE_LIMIT_RPM

Retry-After

/status

KV_REST_API_URL

KV_REST_API_TOKEN

DATA_FILE

npm run claude -- --check

Last updated: August 2026 · hamro.site free AI gateway.