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. These guides walk through the exact screens for the most popular apps.

info

For command-line and editor tools — opencode, Codex CLI, Aider, Continue — the fast path is zs-proxy connect, which writes the config for you. Each of those has a short walkthrough below if you'd rather see exactly what it writes and how to pick a model. The GUI apps in this section expect you to fill in a base URL by hand, and Hermes / OpenClaw / Pi are agents connect configures too.

Before you start​

Every guide on this page assumes the same three things. Do these once and they apply to all of them:

  1. The proxy is installed and running. 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 wallet has a little money in it. zs-proxy fund — 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 (your proxy's address + /v1). Don't add /chat/completions — the app appends the rest itself.
API keyAnything non-empty — zerosignal, not-checked, a single character. The proxy discards it; admission is your wallet's on-chain seal, not a key. Only fill it in because some apps refuse a blank field.

Picking a model​

Whichever app you connect, requests must name a concrete model id from the live catalog — there's no "Auto" lane outside the chat app. Apps that support it will auto-fill a model dropdown by reading GET /v1/models; others give you a text field where you 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​

Some of these apps (Open WebUI, LibreChat) run in a container by default. A container can't reach localhost:9376 on your machine — inside the container, localhost is the container. 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 — and it's single-user, so 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, or via its own setup wizard.

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

Using an app that isn't listed? The recipe is the same everywhere — 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​