Warp Gateway

A small free CLI gateway that lets Warp use ChatMock/Codex and local OpenAI-compatible LLMs through one custom inference endpoint.

Warp -> ngrok free tunnel -> local gateway -> ChatMock/Codex
                                      ├── LM Studio (optional)
                                      └── Lemonade (optional)

Install

npm install -g @gustavonline/warp-gateway
warp-gateway setup
warp-gateway run

setup asks for your ngrok authtoken once and runs ChatMock login when needed.

ngrok token page: https://dashboard.ngrok.com/get-started/your-authtoken

Daily use

warp-gateway run

Keep the terminal open while using Warp. Press Ctrl+C to stop the gateway, ChatMock, and ngrok.

The CLI prints the current Warp values:

Endpoint URL: https://xxxx.ngrok-free.dev/v1
API key:      <gateway key>
Model:        gpt-5.5

Free ngrok URLs can change. Warp Gateway stores the last URL and gateway key:

• if the ngrok URL is unchanged, the gateway key is reused and Warp settings should still work;
• if the ngrok URL changed, a new gateway key is generated and the terminal clearly says to update Warp;
• the ngrok authtoken itself is not rotated or changed by normal runs.

Warp configuration

In Warp Settings, find Custom Inference Endpoint and use the values printed by warp-gateway run.

Recommended model:

gpt-5.5

Thinking aliases:

gpt-5.5-minimal
gpt-5.5-low
gpt-5.5-medium
gpt-5.5-high
gpt-5.5-xhigh

Commands

warp-gateway setup              # first-time setup / repair
warp-gateway setup --reset-ngrok-token  # replace invalid/revoked ngrok token
warp-gateway run                # start ChatMock, ngrok, and gateway in foreground
warp-gateway run --rotate-key   # force a new gateway API key
warp-gateway start              # start everything in the background
warp-gateway stop               # stop saved gateway/ChatMock/ngrok background pids
warp-gateway status             # show endpoint, API key, pids, and config paths
warp-gateway logs -n 50         # show recent gateway request logs
warp-gateway logs --tail        # follow gateway logs
warp-gateway logs --file ngrok  # show ngrok stdout log
warp-gateway config providers   # list providers
warp-gateway config enable lmstudio
warp-gateway config set adapters.lmstudio.baseUrl http://127.0.0.1:1234/v1
warp-gateway doctor             # check node/python/chatmock/ngrok/config
warp-gateway update             # update the global CLI from npm
warp-gateway update --check     # only check whether an update exists
# Normal commands also notify once per day when a newer npm version exists.

Short alias:

wgw run

Config and logs

Runtime files are stored outside the npm package:

• Windows: %APPDATA%/warp-gateway/
• macOS: ~/Library/Application Support/warp-gateway/
• Linux: ${XDG_CONFIG_HOME:-~/.config}/warp-gateway/

Files include:

config.json
state.json
logs/gateway.log
logs/chatmock.out.log
logs/chatmock.err.log
logs/ngrok.out.log
logs/ngrok.err.log
tools/ngrok/        # local downloaded ngrok on Windows/Linux when needed

On macOS, downloaded executable tools are stored in ~/Library/Caches/warp-gateway/tools/ instead of Application Support so Python/CLI shebangs do not break on paths with spaces:

~/Library/Caches/warp-gateway/tools/ngrok/
~/Library/Caches/warp-gateway/tools/chatmock-venv/

warp-gateway setup installs ChatMock into an isolated local Python virtual environment, so it works with Homebrew/macOS Python installations that block global pip install.

Providers

Default:

• ChatMock/Codex on http://127.0.0.1:8000/v1
• Uses OpenAI/Codex OAuth during warp-gateway setup; no local model is required.

Optional/local:

• LM Studio on http://127.0.0.1:1234/v1 with discovered models as lmstudio/<model>
• Lemonade on http://127.0.0.1:13305/v1 with discovered models as lemonade/<model>

Provider config examples:

warp-gateway config providers
warp-gateway config enable lmstudio
warp-gateway config disable lemonade
warp-gateway config set adapters.lmstudio.baseUrl http://127.0.0.1:1234/v1
warp-gateway config set adapters.lemonade.baseUrl http://127.0.0.1:13305/v1

If the gateway is running, config changes restart it automatically. If it is stopped, run warp-gateway start afterwards.

The gateway uses a generic OpenAI-compatible provider shape, so more providers can be added via config later.

npm publishing / supply-chain safety

This package is intended to be published with npm Trusted Publishing from GitHub Actions, not a long-lived npm token.

Recommended npm trusted publisher settings:

• GitHub owner/repo: gustavonline/warp-gateway
• Workflow filename: publish.yml
• Allowed action: npm publish

Release flow:

npm test
npm version patch
git push origin main --follow-tags

The publish workflow runs on pushes to main and release tags. It checks whether the package version already exists on npm and only publishes new versions.

Installed CLIs check npm at most once per day during normal commands and print:

Update available for Warp Gateway: <current> -> <latest>
Run: warp-gateway update

Set WARP_GATEWAY_NO_UPDATE_CHECK=1 to disable the background notification.

The publish workflow uses OIDC and provenance:

npm publish --provenance --access public

The package uses a files allowlist and scripts/check-pack.js to block local config, logs, tools, ngrok binaries, and secrets from being included in the npm tarball.