HTTP API

Joocode works as a fully local OpenAI-compatible gateway for any compatible application, without the desktop integrations.

text

Base URL: http://127.0.0.1:10100/v1
API key:  any non-empty local placeholder
Model:    provider/model

Joocode ignores the placeholder client key and uses credentials from the original provider source. It never exposes provider credentials to the client.

Endpoints

bash

curl http://127.0.0.1:10100/healthz
curl http://127.0.0.1:10100/readyz
curl http://127.0.0.1:10100/api/status
curl http://127.0.0.1:10100/api/providers
curl http://127.0.0.1:10100/api/metrics
curl http://127.0.0.1:10100/v1/models

/healthz — process liveness.
/readyz — whether the registry can route requests, plus model/provider counts and status.
/api/status — privacy-safe uptime and request counters plus passive provider runtime state.
/api/providers — non-secret provider/model catalog and source discovery reports.
/api/metrics — the same data in Prometheus text format.
/v1/models — the merged model registry.

Prompts, bodies, response content, provider URLs, headers, and credentials are never stored or exposed.

Create a response

bash

curl http://127.0.0.1:10100/v1/responses \
  -H 'content-type: application/json' \
  -d '{
    "model": "provider/model",
    "input": "Reply with hello",
    "stream": false
  }'

Use POST /v1/chat/completions for OpenAI-compatible clients. Both endpoints support SSE streaming and tool calls.

WebSocket

Responses WebSocket mode is available on the same resource:

text

ws://127.0.0.1:10100/v1/responses

Server-to-server Realtime WebSocket relay for native OpenAI-compatible providers:

text

ws://127.0.0.1:10100/v1/realtime?model=provider/model

LAN or remote binding

Loopback keeps the zero-configuration placeholder-key behavior. Binding to a LAN or non-loopback interface requires a real admission token. jcx hub is the lightweight remote mode for LAN, VPN, and tailnet use.

bash

export JOOCODE_API_AUTH_TOKEN='replace-with-a-long-random-token'
export JOOCODE_MANAGEMENT_AUTH_TOKEN='replace-with-a-different-random-token'
export JOOCODE_ALLOWED_ORIGINS='https://app.example.com,https://admin.example.com'
export JOOCODE_REMOTE_REQUESTS_PER_SECOND=20
export JOOCODE_REMOTE_REQUEST_BURST=40
jcx hub --host 0.0.0.0 --port 10100

Remote clients send Authorization: Bearer <token> or x-joocode-api-key: <token>. Joocode rejects non-loopback startup without JOOCODE_API_AUTH_TOKEN, disables remote CORS unless origins are listed, and applies a token-bucket rate limiter to authenticated remote traffic.