ZeroFare
Console Get started
Docs / Getting started

Getting started

ZeroFare has two entry points. Pick one — your application code is the same against both.

Λ

Run the edge locally

For development, privacy, or offline use. Your provider keys stay in a local vault; nothing leaves your machine except calls to the providers themselves.

◆

Use the hosted gateway

For production apps without ops. Point your client at our TLS endpoint and authenticate with a ZeroFare API key.

Path A — the local edge

  1. Build and install

    Clone the public repo, install with pnpm, and build. Validation and installation should run from a fast mirror, not the source drive: 

    git clone https://github.com/zerofare/free-llm && cd free-llm
tools/fast-mirror.sh "$PWD" /tmp/zerofare-validation/public
cd /tmp/zerofare-validation/public
corepack pnpm install
pnpm build

  2. Initialize the edge

    zerofare init creates a schema-enforced config and an encrypted local vault, and prints the local bearer token once: 

    umask 077
printf '%s\n' 'a-long-unique-vault-passphrase' | \
  pnpm zerofare init --config "$HOME/.config/zerofare/config.json"

    Easiest path: add a certified free provider from ZeroFare's curated catalog in two commands — zerofare onboard provider --preset groq then zerofare onboard credential --preset groq (key from the providers list, validated by shape before it reaches the vault). Prefer hand-rolling? Write the passphrase, a newline, and the provider key to stdin for zerofare credentials set --id … --provider …, and add providers from a non-secret JSON file with zerofare providers add --file.

  3. Check and serve

    pnpm zerofare doctor
printf '%s\n' 'a-long-unique-vault-passphrase' | pnpm zerofare serve

    The edge binds 127.0.0.1:8787, authenticates before parsing request bodies, and exposes the compat surfaces, model listing, receipt, health/readiness routes.

  4. Make a request

    curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer $ZEROFARE_LOCAL_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"model":"…","messages":[{"role":"user","content":"hi"}]}'
Local dev reality check: a fresh local install is a development-only setup — real provider origin dispatch is disabled, readiness stays false, and /v1/models is empty until routes are provisioned. The served receipt is a minimal denial/finalization record. The hosted gateway path below is the one that's commercially wired today.

Path B — the hosted gateway

  1. Create your tenant

    Open the console and sign in with a management credential. On the early-access deployment tenants are provisioned for you — contact us and you'll receive your API key and console credential.

  2. Store your key

    Keys look like zf_… and are shown exactly once at creation. Put one in your environment: 

    export ZERFARE_API_KEY=zf_…   # shown once — store it in your secret manager

  3. Call the gateway

    curl https://150-136-150-135.sslip.io:8443/v1/messages \
  -H "Authorization: Bearer $ZERFARE_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"…","max_tokens":64,
       "messages":[{"role":"user","content":"hi"}]}'

    Or with the TypeScript SDK:

    import { ZeroFareClient } from "@zerofare/sdk";

const zf = new ZeroFareClient({
  baseUrl: "https://150-136-150-135.sslip.io:8443",
  apiKey: process.env.ZERFARE_API_KEY!,
});

const reply = await zf.messages({
  model: "…",
  max_tokens: 64,
  messages: [{ role: "user", content: "hi" }],
});

Verify authentication

# no / wrong key -> terse 401 (fail-closed, nothing enumerable)
curl -s -o /dev/null -w '%{http_code}\n' \
  https://150-136-150-135.sslip.io:8443/management/v1/sessions

# real key -> 200 with your key metadata
curl -s https://150-136-150-135.sslip.io:8443/management/v1/api-keys \
  -H "Authorization: Bearer $ZERFARE_API_KEY"

Next steps