Skip to main content

How-to guides

The proxy is a drop-in OpenAI endpoint, so most apps that can talk to a "custom" or "OpenAI-compatible" provider can use ZeroSignal with two values: a base URL and a throwaway API key.

info

zs-proxy connect writes the config for opencode, Codex CLI, Aider, Continue, Hermes, OpenClaw, and Pi; their guides show what it writes and how to pick a model. The GUI apps take the base URL by hand.

Before you start​

  1. The proxy is set up and running. You've signed it in with zs-proxy wallet login and started it with zs-proxy proxy start — see the Quick start. connect and these apps read the live endpoint, so the proxy has to be up.
  2. Your account has a little money in it. Add funds in the chat app, or with zs-proxy fund for a wallet only the proxy uses. A couple of dollars covers a lot of chatting. See Wallet & funding.
  3. You know your base URL. It's your proxy's listen address with /v1 on the end — http://localhost:9376/v1 unless you changed server.listen in Configuration.

The two values every app needs​

Field the app asks forWhat to enter
Base URL / API host / endpointhttp://localhost:9376/v1. Don't add /chat/completions; the app appends the rest itself.
API keyAnything non-empty — zerosignal, not-checked, a single character. Some apps refuse a blank field. The proxy discards the key, since your wallet's on-chain seal is the credential.

Picking a model​

Requests must name a concrete model id from the live catalog; there's no "Auto" lane outside the chat app. Some apps fill a model dropdown from GET /v1/models; others give you a text field to type an id. To see the list yourself:

curl http://localhost:9376/v1/models | jq -r '.data[].id'

See Models & operators for what's on the network.

Running the app in Docker​

Open WebUI and LibreChat run in a container by default. Inside a container, localhost is the container itself, so it can't reach localhost:9376 on your machine. Two things change:

  • Point the app at http://host.docker.internal:9376/v1 instead of localhost. On Linux, also add --add-host=host.docker.internal:host-gateway to the container so that name resolves.
  • Bind the proxy where the container can reach it. By default the proxy listens on loopback only (127.0.0.1:9376), which a container can't dial. Set server.listen to 0.0.0.0:9376 (or PROXY_SERVER_LISTEN=0.0.0.0:9376) so it accepts the connection.
warning

Binding beyond 127.0.0.1 exposes the proxy to other machines. The proxy is single-user: anyone who can reach it spends your balance, with no key required. Only do this on a machine you trust and behind a firewall, and set a spend cap as a backstop.

The guides​

SillyTavern

Roleplay and character-chat front end. Native app; connects in a few clicks.

Open WebUI

Self-hosted ChatGPT-style web UI. Usually runs in Docker — mind the networking note above.

LibreChat

Self-hosted multi-model chat. Configured with a librechat.yaml custom endpoint.

Chatbox

Cross-platform desktop chat client. Native app; add a custom provider.

Cherry Studio

Desktop AI client with a custom-provider option.

Hermes

Nous Research CLI/TUI agent. Configured by zs-proxy connect hermes --plugin, which installs the ZeroSignal plugin too.

OpenClaw

Personal AI agent. Configured by zs-proxy connect openclaw.

Pi

Minimal terminal coding agent. Configured by zs-proxy connect pi.

opencode

Terminal coding agent. Configured by zs-proxy connect opencode.

Codex CLI

OpenAI's coding agent. Configured by zs-proxy connect codex.

Aider

Command-line pair programmer. Configured by zs-proxy connect aider.

Continue

VS Code / JetBrains assistant. Configured by zs-proxy connect continue.

info

For an app that isn't listed, set the base URL and a placeholder key from the table above. The generic instructions are in Connecting AI tools → Manual setup.

What's next​