Русский · English · 简体中文

FreeNIMAPI

One local bridge between NVIDIA NIM and your coding agents.
Codex gets Responses, Claude Code gets Messages, and Hermes and OpenCode get Chat Completions.

Quick start · Connect agents · How it works · Verification · Security

Important

FreeNIMAPI is a local proxy, not a local model. The bridge runs on your machine, while inference runs on NVIDIA's hosted service and remains subject to trial access, quotas, model availability, and model licenses.

55/55	3 protocols	4 client families	1 local address
local tests	Chat · Messages · Responses	Hermes · Codex · Claude · OpenCode	`127.0.0.1:3000`

Full table of contents

What FreeNIMAPI is
Quick start
Get an NVIDIA API key
Connect coding agents
How it works
Supported APIs
Models
Real-agent verification
Security
Advanced configuration
Limitations
Troubleshooting
Documentation
License and service terms

What FreeNIMAPI is

Modern coding agents speak different API dialects. FreeNIMAPI uses NVIDIA's hosted route as its upstream Chat Completions transport, then exposes the format each local client expects.

Client	What it expects	What FreeNIMAPI exposes
Codex	OpenAI Responses	`POST /v1/responses`
Claude Code	Anthropic Messages	`POST /v1/messages`
Hermes Agent	OpenAI Chat Completions	`POST /v1/chat/completions`
OpenCode	Chat Completions or Responses	both routes

FreeNIMAPI translates requests, structural tool calls, tool results, and terminal stream events. The NVIDIA credential stays inside the proxy process; the agent receives a separate local credential.

Quick start

Requirements

macOS, Linux, or Windows;
Git;
Node.js 20+;
an NVIDIA API key for hosted NIM.

1. Install and start

git clone https://github.com/ForgetMeAI/FreeNIMAPI.git
cd FreeNIMAPI
npm ci
npm run start:guided

The launcher requests the NVIDIA key without echoing characters, does not write it to disk, and starts the proxy at http://127.0.0.1:3000. Keep this terminal open. Press Ctrl+C to stop it.

2. Check it from a second terminal

cd FreeNIMAPI
FREENIM_LOCAL_API_KEY=freenim-local npm run health

PowerShell:

$env:FREENIM_LOCAL_API_KEY="freenim-local"
npm run health

A successful health check means the local gateway is ready for clients. It does not spend NVIDIA quota.

Tip

Use npm run start:secure when you want a unique local client key. It asks for both the NVIDIA key and the downstream client key without echoing either value.

Get an NVIDIA API key

Sign in to the NVIDIA API Catalog.
Open Settings → API keys.
Create a key and store it in a secret manager.
Paste it only into the hidden prompt opened by npm run start:guided.

For the official distinction between NVIDIA_API_KEY and an NGC key, see NVIDIA authentication and API keys.

Caution

Never paste the NVIDIA key into Codex, Claude Code, Hermes, OpenCode, project configuration, issues, screenshots, or video commands. Coding agents should only receive the separate FREENIM_LOCAL_API_KEY.

Connect coding agents

The examples below assume guided mode bound to loopback. First expose the separate local key to your client shell:

export FREENIM_LOCAL_API_KEY=freenim-local

Client	Wire API	Tested version	Current qualification
Hermes Agent	Chat Completions	0.16.0	scripted transport PASS; live NVIDIA PENDING
Codex	Responses	0.144.2	historical live PASS; fresh scripted PASS
Claude Code	Messages	2.1.169	historical live PASS; fresh scripted PASS
OpenCode	Chat / Responses	1.17.18	historical live Chat PASS; Responses PENDING live

Statuses are tied to the 2026-07-17 snapshot. The verification section defines historical, scripted, and live precisely.

Hermes Agent · Chat Completions

Add the equivalent custom provider to an isolated Hermes profile:

model:
  default: nim-auto
  provider: custom
  base_url: http://127.0.0.1:3000/v1
  api_key: freenim-local
  api_mode: chat_completions

Use freenim-local only for loopback guided mode. For any network exposure, generate a unique local key with npm run start:secure. The exact isolated configuration used by the E2E runner is documented in docs/AGENT_E2E.md.

Codex · Responses

Add the provider to $CODEX_HOME/config.toml, normally ~/.codex/config.toml. Prefer a separate CODEX_HOME for tests.

model = "nim-auto"
model_provider = "freenim"

[model_providers.freenim]
name = "FreeNIMAPI"
base_url = "http://127.0.0.1:3000/v1"
env_key = "FREENIM_LOCAL_API_KEY"
wire_api = "responses"
requires_openai_auth = false

FreeNIMAPI answers Codex model-catalog requests with Codex-specific ModelInfo metadata and advertises custom/freeform apply_patch.

Claude Code · Anthropic Messages

ANTHROPIC_BASE_URL points to the server root, without /v1:

Do not choose an item on Claude Code's login screen: an arbitrary gateway is not configured through that menu. Stop that screen with Ctrl+C, then paste the entire block below into the same terminal that will launch claude. The block supplies the guided-mode loopback key even if you skipped the shared export FREENIM_LOCAL_API_KEY above:

export FREENIM_LOCAL_API_KEY="${FREENIM_LOCAL_API_KEY:-freenim-local}"
export FREENIM_MODEL="${FREENIM_MODEL:-nim-auto}"
export ANTHROPIC_BASE_URL=http://127.0.0.1:3000
export ANTHROPIC_AUTH_TOKEN="$FREENIM_LOCAL_API_KEY"
export ANTHROPIC_MODEL="$FREENIM_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$FREENIM_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$FREENIM_MODEL"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$FREENIM_MODEL"
export ANTHROPIC_CUSTOM_MODEL_OPTION="$FREENIM_MODEL"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="FreeNIMAPI / $FREENIM_MODEL"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
claude --model "$FREENIM_MODEL"

On the first launch, Claude Code may still ask for a theme, show its security notice, and ask whether you trust the folder. Those prompts are expected; the login-method screen is not. /status should show http://127.0.0.1:3000 and ANTHROPIC_AUTH_TOKEN, while /model includes FreeNIMAPI / nim-auto. To use another model, set something like export FREENIM_MODEL=minimax-m3 before the block.

This is technical compatibility through Claude Code's official LLM gateway mechanism. Anthropic does not guarantee the behavior of non-Claude models.

OpenCode · Chat Completions / Responses

Add these providers to a project opencode.json or your global OpenCode configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "freenim-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "FreeNIMAPI Chat",
      "options": {
        "baseURL": "http://127.0.0.1:3000/v1",
        "apiKey": "{env:FREENIM_LOCAL_API_KEY}"
      },
      "models": {
        "nim-auto": { "name": "FreeNIM nim-auto" }
      }
    },
    "freenim-responses": {
      "npm": "@ai-sdk/openai",
      "name": "FreeNIMAPI Responses",
      "options": {
        "baseURL": "http://127.0.0.1:3000/v1",
        "apiKey": "{env:FREENIM_LOCAL_API_KEY}"
      },
      "models": {
        "nim-auto": { "name": "FreeNIM nim-auto" }
      }
    }
  }
}

Select either freenim-chat/nim-auto or freenim-responses/nim-auto.

How it works

A coding agent sends a request in its own wire format.
FreeNIMAPI normalizes system messages, tools, tool results, and the streaming lifecycle.
The proxy sends a hosted NVIDIA Chat Completions upstream request.
The result is converted back into Responses, Messages, or Chat Completions.
The agent executes a real tool and continues the same loop until its final answer.

Self-hosted NVIDIA NIM may expose additional APIs directly. FreeNIMAPI addresses the narrower hosted API Catalog use case and provides one consistent local endpoint for different clients.

Supported APIs

Method and route	Consumer	Implemented behavior
`POST /v1/chat/completions`	Hermes, OpenCode, OpenClaw	text, native tools, continuation, local SSE
`POST /v1/messages`	Claude Code	`tool_use`, `tool_result`, Anthropic SSE
`POST /v1/messages/count_tokens`	Claude Code	local estimate without spending NVIDIA quota
`POST /v1/responses`	Codex, OpenCode	function/custom tools, `apply_patch`, strict terminal SSE
`GET /v1/models`	OpenAI-compatible clients	alias model catalog
`GET /v1/models?client_version=…`	Codex	Codex `ModelInfo` with freeform `apply_patch`
`GET /health`	operator	sanitized readiness without exposing secrets
`GET /api/diagnostics`	operator	circuits, concurrency, sanitized status
`GET /capabilities`	operator	bridge capability metadata

See docs/API.md for complete request shapes.

Models

Availability snapshot: 2026-07-17.

Alias	NVIDIA upstream	Status
`nim-auto`, `gpt-oss-120b`	`openai/gpt-oss-120b`	default; historical live Codex/OpenCode Chat qualification
`minimax-m3`	`minimaxai/minimax-m3`	candidate; historical Claude workflow, later unstable tool preflight
`glm-5.2`	`z-ai/glm-5.2`	experimental
`deepseek-v4-flash`	`deepseek-ai/deepseek-v4-flash`	experimental
`deepseek-v4-pro`	`deepseek-ai/deepseek-v4-pro`	availability unverified
`kimi-k2.6`	`moonshotai/kimi-k2.6`	deprecated / unsupported

nim-auto is an alias, not a promise of permanent availability. NVIDIA may change its hosted catalog, quotas, endpoint behavior, and model licenses. Check the current model card before use.

Real-agent verification

A 200 OK response or a model saying “I fixed the code” proves nothing. The FreeAPI nominal requires a real installed client and observable tool work:

01	02	03	04	05	06	07
RED	inspect project	real tool event	edit production code	GREEN	exact `PROOF.txt`	separate no-network verifier

Protected tests and package.json are hashed before and after the client run. PASS requires the correct failure → edit → green order, the client's terminal event, and an independent test run after the agent process has stopped.

Honest qualification matrix

Client / wire	Scripted real-client transport	Live NVIDIA native model
Hermes 0.16.0 / Chat	PASS	PENDING
Codex 0.144.2 / Responses	PASS	HISTORICAL PASS · GPT-OSS-120B
Claude Code 2.1.169 / Messages	PASS	HISTORICAL PASS · alias `nim-auto`, historically attributed to MiniMax M3; exact upstream ID was not captured; fresh GPT-OSS did not finish proof/final
OpenCode 1.17.18 / Chat	PASS	HISTORICAL PASS · GPT-OSS-120B
OpenCode / Responses	PASS	PENDING

Scripted proves client configuration, wire translation, tool execution, and artifact verification, but not native-model quality. Historical live runs predate the normative FAAS v1.0 schema and are not retroactively relabeled as current N4 PASS. HISTORICAL PASS values come from retained local legacy reports; raw bundles are not published, so they cannot be independently verified from the public repository alone.

# 55 local unit/integration tests; no network or credentials
npm test

# Real installed clients + deterministic transport
npm run test:agents:mock

# Live NVIDIA endpoint matrix; requires NVIDIA_API_KEY
npm run test:live

# Live coding-agent E2E; requires NVIDIA_API_KEY
npm run test:agents

# Three-language parity and link checks
npm run check:readme

Public sanitized snapshot: docs/evidence/agent-qualification-2026-07-17.json. Methodology and limitations: docs/VERIFICATION.md.

Security

Secret	Where it exists	Where it is sent
`NVIDIA_API_KEY`	FreeNIMAPI process environment only	configured `NVIDIA_BASE_URL`; the official NVIDIA hosted endpoint by default
`FREENIM_LOCAL_API_KEY`	local client and proxy	configured FreeNIMAPI address; loopback by default

.env is not loaded automatically;
browser origins are denied by default;
non-loopback binding without a separate local key is rejected by default;
prompts, tool results, upstream bodies, and credentials are not logged;
retries, response size, request deadline, and concurrency are bounded;
E2E clients receive a clean environment without the NVIDIA key;
there is no multi-account rotation, quota bypass, cookie pooling, or leaked-key workflow.

Warning

freenim-local is suitable only on 127.0.0.1. For network access, use npm run start:secure, TLS, and your own access controls. If you change NVIDIA_BASE_URL, the upstream key is sent to that host—use only a trusted endpoint. FREENIM_ALLOW_UNAUTHENTICATED_REMOTE=true intentionally disables the remote-bind guard and is not recommended.

Read the full threat model in docs/SECURITY.md.

Advanced configuration

Variable	Default	Purpose
`HOST`	`127.0.0.1`	listening address
`PORT`	`3000`	local port
`NVIDIA_BASE_URL`	`https://integrate.api.nvidia.com/v1`	hosted upstream
`NIM_DEFAULT_MODEL`	`nim-auto`	default alias
`NIM_TIMEOUT_MS`	`120000`	full request deadline
`NIM_MAX_RETRIES`	`2`	retryable-error retries
`NIM_MAX_CONCURRENCY`	`1`	concurrent upstream generations
`FREENIM_CORS_ORIGINS`	empty	allowed browser origins
`FREENIM_LOCAL_API_KEY`	empty	separate downstream authentication
`FREENIM_ALLOW_UNAUTHENTICATED_REMOTE`	`false`	dangerous remote-auth guard override; not recommended
`NIM_TEXT_TOOL_FALLBACK`	`false`	text fallback; forbidden during real-agent qualification

For CI or a secret manager, run npm start with NVIDIA_API_KEY and a unique FREENIM_LOCAL_API_KEY in the environment. Run npm run doctor first.

Limitations

NVIDIA API Catalog is a trial/evaluation service, not a production SLA or “free forever.”
Hosted models can be slow, change quotas, or temporarily reject native tools.
Downstream SSE is synthesized after the complete upstream response; time to first token can equal the full NVIDIA generation time.
The bridge supports text. Images, documents, signed thinking blocks, hosted web search, MCP namespaces, and computer-use items are not translated.
previous_response_id is not stored server-side; the next Responses turn must include the conversation items it needs.
count_tokens is a rough local estimate.
A model appearing in the catalog does not prove that it can use tools correctly.

Production use requires a separate commercial endpoint and requalification of the exact client × model × protocol tuple.

Troubleshooting

Symptom	Check
`health` returns `401`	both terminals must use the same `FREENIM_LOCAL_API_KEY`
Claude Code cannot connect	`ANTHROPIC_BASE_URL` must not include `/v1`
Codex cannot see the model or tools	`base_url` must end in `/v1`, with `wire_api = "responses"`
The agent talks but never calls tools	the selected model did not emit a structural tool call; this is a model/preflight failure
Responses are very slow	the trial upstream can take minutes; inspect diagnostics and the selected model
Requests fail after changing the bind address	return to loopback and verify auth/CORS with `npm run doctor`

npm run doctor
FREENIM_LOCAL_API_KEY=freenim-local npm run health

If the problem is reproducible, open an issue without keys, cookies, full prompt logs, or private paths.

Documentation

Document	Purpose
Russian quick start	minimal installation path
API reference	routes and payloads
Architecture	bridge layers and data flow
Agent E2E	real behavioral nominal
Verification	matrix and qualifications
Security	threat model and safe operation
Public evidence snapshot	machine-readable sanitized status

For a pull request:

never add real credentials or raw agent reports;
run npm test and npm run check:readme;
label protocol tests, scripted client tests, and live upstream evidence separately;
never promote a client status without complete evidence for the required class.

License and service terms

FreeNIMAPI source code is available under the MIT License.

Hosted NVIDIA APIs are governed by the NVIDIA API Trial Terms, and each model has its own license. The trial service is intended for limited testing and evaluation; do not send confidential data to it.

Did FreeNIMAPI help?
Give the repository a ⭐, report reproducible failures through Issues,
and follow practical AI tooling at @forgetmeai.

Русский · English · 简体中文 · Back to top ↑

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FreeNIMAPI

What FreeNIMAPI is

Quick start

Requirements

1. Install and start

2. Check it from a second terminal

Get an NVIDIA API key

Connect coding agents

How it works

Supported APIs

Models

Real-agent verification

Honest qualification matrix

Security

Advanced configuration

Limitations

Troubleshooting

Documentation

License and service terms

FilesExpand file tree

README.en.md

Latest commit

History

README.en.md

File metadata and controls

FreeNIMAPI

What FreeNIMAPI is

Quick start

Requirements

1. Install and start

2. Check it from a second terminal

Get an NVIDIA API key

Connect coding agents

How it works

Supported APIs

Models

Real-agent verification

Honest qualification matrix

Security

Advanced configuration

Limitations

Troubleshooting

Documentation

License and service terms