grok-api

OpenAI-compatible local API bridge so tools like Kilo Code can use Grok Build CLI models (today: Grok 4.5) that the stock xAI provider may not list.

Kilo / any OpenAI client  →  http://127.0.0.1:3001/v1  →  cli-chat-proxy.grok.com
                                (this bridge)              (uses your grok login)

Prerequisites

1. Grok Build CLI installed and on PATH
2. Signed in: grok login
3. Docker + Compose or Node.js 18+

Quick start (Docker)

git clone https://github.com/michaelotis/grok-api.git
cd grok-api
docker compose up -d --build

Verify:

curl -sS http://127.0.0.1:3001/health
curl -sS http://127.0.0.1:3001/v1/models

The compose file mounts ~/.grok → /auth (directory, not a single file) so token refresh after grok login is visible inside the container. CLI version is read automatically from ~/.grok/version.json.

After a fresh grok login, restart if needed:

docker compose restart

Optional: WSL auto-start helper

./scripts/install-wsl.sh

Builds, starts the container with restart: unless-stopped, and tries to enable Docker on WSL boot (systemd=true in /etc/wsl.conf required).

Quick start (Node, no Docker)

npm start
# or
npm run dev   # watch mode

Kilo Code setup

Settings UI

Field	Value
Provider API	OpenAI Compatible
Base URL	http://127.0.0.1:3001/v1
API key	leave empty (or any placeholder)
Model ID	grok-4.5

Select grok-cli/grok-4.5 in the model picker (provider id is whatever you name it; see example config).

Config file

Copy examples/kilo.jsonc into your Kilo config (often ~/.config/kilo/kilo.jsonc) and merge the provider.grok-cli block. Suggested provider options:

• timeout: 600000 (10 minutes)
• chunkTimeout: 180000 (3 minutes — long plan/report turns can pause between SSE chunks)

Remote / non-local clients

Bind is 127.0.0.1 by default (local only). For another machine, change the compose port bind carefully and use TLS/VPN — do not expose this unauthenticated on a public interface.

Models

Whatever the host CLI exposes (grok models). As of Grok Build 1.x that is typically grok-4.5 only.

Requested model	Upstream
grok-4.5 (default)	grok-4.5 — reasoning_effort high/medium/low

Legacy aliases may still be rewritten in the bridge but are not advertised and may fail upstream.

How it works

Mode	Behavior
proxy (default)	Forward Chat Completions to https://cli-chat-proxy.grok.com/v1 with your login token. Streaming + tool calls preserved.
headless	Spawns grok -p per request (debug only; no OpenAI-style tool_calls).
auto	Proxy first, headless on failure.

GROK_API_MODE=headless npm start

The bridge also normalizes common Cursor/Composer tool argument shapes to what Kilo expects (paths, glob patterns, write content, etc.).

Environment variables

Variable	Default	Description
GROK_API_PORT	3001	Listen port
GROK_API_HOST	127.0.0.1	Bind address (Docker image uses 0.0.0.0 inside the container)
GROK_API_MODE	proxy	proxy, headless, or auto
GROK_API_DEFAULT_MODEL	grok-4.5	Default when the request omits model
GROK_API_PROXY_URL	https://cli-chat-proxy.grok.com/v1	Upstream
GROK_API_AUTH_PATH	~/.grok/auth.json	Auth file (/auth/auth.json in Docker)
GROK_API_CLI_VERSION	(auto)	Optional override; else version.json next to auth
GROK_API_REASONING_EFFORT	high	Injected for Grok 4.5
GROK_API_EFFORT	max	Legacy Composer path only
GROK_API_CWD	cwd	Working directory for headless mode

Troubleshooting

Symptom	Fix
No auth token / 401	grok login, then docker compose restart
Connection refused	docker compose up -d and check curl localhost:3001/health
SSE / stream timeouts in Kilo	Raise provider chunkTimeout (e.g. 180000)
Wrong CLI version in /health	Ensure ~/.grok/version.json exists (updated by the CLI)

Security

• No API keys are stored in this repo. Auth is your ~/.grok/auth.json from grok login.
• The server binds to localhost by default; treat it as a local sidecar.
• Do not commit auth.json, .env files, or tokens.

License

MIT — see LICENSE.