Quick start

Get merido running locally and make your first request in a few minutes. The local profile needs no external services — it uses an embedded SQLite database under ~/.merido.

Prerequisites

• Rust — stable toolchain, edition 2024 (Rust 1.85+). The repo pins this via rust-toolchain.toml.
• bun — to build the dashboard SPA (bun.sh). The server crate embeds the built dashboard at compile time, so you must build it before compiling the server.

1. Build the dashboard

dashboard/dist is gitignored, so a fresh checkout has none. Build it once with bun:

cd dashboard && bun install && bun run build && cd ..

2. Run the gateway

cargo run -p merido -- start          # API + dashboard on http://127.0.0.1:8788

To override the port:

cargo run -p merido -- start --port 9000     # or set MERIDO_PORT

What you get

A single process now serves, all on http://127.0.0.1:8788:

• the API at /v1 (OpenAI / Anthropic / Gemini compatible),
• the dashboard at /app,
• a landing page at /,
• these docs at /docs,
• a health check at /healthz.

By default the local profile is wide open — no auth on the dashboard or the API. That's fine for your own machine; before exposing it publicly, read Deploy to production.

3. First end-to-end test

a. Create a client (gateway) key

This is the key your tools use to authenticate to merido (distinct from upstream provider credentials — see Add providers & keys).

cargo run -p merido -- keys create --name "my-laptop"

It prints the key once — copy it now, it isn't shown again. (You can also create one in the dashboard under Gateway keys.) Add --ttl-seconds <n> for a key that expires.

b. Add an upstream provider

Give merido a real provider API key so it can call upstream:

cargo run -p merido -- providers add --provider openai --api-key sk-...

The base URL defaults to the provider's known endpoint; override it with --base-url. You can also add providers (API key or OAuth) from the dashboard Providers page.

c. Make a request

Point any OpenAI-compatible client at /v1, using your merido key as the bearer token:

curl http://127.0.0.1:8788/v1/chat/completions \
  -H "Authorization: Bearer <your-merido-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Say hello from merido."}]
  }'

The model is a provider/model reference (or a virtual model name). Open the dashboard and you'll see the request, its tokens, and its cost appear live.

Next steps

• Connect a coding CLI — wire Claude Code / Codex / Cursor to merido.
• Virtual models & fallback — one name, many candidate targets.
• Token saving — cut tokens on every request.