Relay
Relay Overview
Relay is a hosted, metered tier-3 proxy: tier 1 and tier 2 stay free, tier 3 AI fallback is usage-based, and you choose who supplies the AI provider key.
Need the shortest path?
Use Quick Start when you want the smallest working route → scan → graph → run flow first.
Something feels off?
Inspect scan output, graph state, active route/context, and dispatch in a practical order.
Need the full surface?
Browse all runtime methods, hooks, extension points, and lifecycle APIs.
@cinder/relay is a real, working prototype of this billing/metering model, not a hands-off managed service yet. See known limitations before putting real money behind it.
@cinder/relay is the only way to add tier-3 AI fallback to a Cinder app: a hosted, metered proxy with real accounts, metering, and billing already built in.
The model
- Tier 1 and tier 2 stay free. They run entirely in the browser SDK - nothing to meter, nothing to pay for.
- Tier 3 is usage-based. A project tops up a wallet, and every real fallback call deducts exactly what it cost, priced from the provider's own real token usage. A project at zero balance never reaches the real AI provider at all, not even once.
- A failed call is never billed. The balance is only debited after a real, successful response.
- Who supplies the AI provider key is a per-project choice, made once when the project is created:
"developer"- your own key, stored once, reused for every call."end_user"- never stored. Arrives with each request via thex-end-user-ai-keyheader, since it belongs to whoever is using the app, not to the developer's account.
Connecting your app
Point your app's Cinder.init() config at a hosted Relay instance's /v1/relay/infer endpoint, using a project's API key as the bearer token. See the pages in this section for account/project setup and billing.
Key pages
Accounts and Projects
Sign up, log in, and create a project to get a real relay API key.
Billing and Usage
Top up a project's wallet, read its balance, and inspect its usage history.
Infer Endpoint
The metered call itself - request shape, the end-user key header, and what gets billed.
Dashboard
There's a real UI for all of this at /relay - sign up, create projects, see real API keys and balances, top up, and watch usage history, without touching curl.
Continue reading