[ docs · guides ]

Gateway, accounts & keys

The gateway at grist.lol is the only hosted piece of Grist. It holds accounts, API keys, routing, and spend caps — and nothing else. Your code is executed on your machine, never in the cloud.

Accounts

Anyone can create an account: name and email, or sign in with Google. The account is ready on the spot — no invite, no waitlist. One account can hold several API keys, so a laptop, a desktop, and a CI box never have to share a credential.

API keys

Named and independent. Each key has a name and can be revoked on its own, without touching the others.
Shown once. A key's secret is displayed exactly once, at creation. After that it exists only as a hash on the gateway — if you lose it, mint a new one.
Attributed spend. Usage is recorded per key, so you can always see which key spent what.

Bring your own provider key

Inference runs on your provider account, not Grist's. Attach a key from OpenRouter, Vercel AI Gateway, or any custom OpenAI-compatible endpoint. Provider keys are encrypted at rest (AES-256-GCM), inference bills directly to your provider account, and Grist adds zero markup. The gateway routes; your key pays.

Spend caps are hard

Every key carries a spend cap, and the cap is enforced before inference is bought — not reconciled after. A request that would exceed the cap is refused with a 402 and no model call is made. There is no overage and no surprise bill; the cap is the bill's ceiling by construction.

Rungs, not models

Clients never name a vendor model. They name a rung — cheapest, medium, frontier, premium — and the gateway resolves the rung to the model behind it. Swap what a rung points to in your dashboard and every client follows, with nothing to reinstall or reconfigure.

Signing in on the desktop

The desktop app signs in two ways: a device flow, where the app shows a code and you approve it in your browser, or by pasting an API key directly. Either way the credential lands in the same local config the CLI uses — see the desktop app.

What transits the gateway

Prompts transit the gateway on their way to your provider. Source code does not: tools run in your local working tree, and the gateway never receives your files. Grist does not train on your code.

The split is the design: the gateway is a control plane (accounts, keys, caps, routing). The data plane — your tree, your tools, your diffs — stays on your machine.

Attach a key over the API

The dashboard flow has an API equivalent. Attach your provider key with your Grist key:

curl -s -X POST https://grist.lol/v1/provider \
  -H "X-Grist-Api-Key: grist_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"provider": "openrouter", "api_key": "sk-or-..."}'

provider is openrouter, vercel, or custom; custom also needs a base_url. Prefer an AI-gateway key: it reaches every model on every rung, while a direct provider key limits all rungs to that provider’s models.

Check spend

GET /v1/usage returns spend broken down by rung — spent_usd, cap_usd, remaining_usd, and by_rung — so you can see exactly where the money went. The dashboard shows the same numbers.