Skip to content
MelMel
Reference > Troubleshooting

Agent connectivity

When the agent can't reach the backend — what to check.

The Mel agent talks to exactly one backend: the Mel relay. The relay holds provider API keys server-side, resolves auto to a concrete model, and streams responses back to the app — on a paid plan your machine never needs provider keys (on Free you add your own key under Settings → AI → Provider API keys, and it travels with your requests). If the agent can't reach the relay, this page is the checklist.

For the relay's full HTTP surface, see the API reference.

The status pill

The agent footer shows a relay-status pill only when something is wrong:

  • connecting… — Mel is checking the relay's health. Normal for a few seconds after launch.
  • relay offline — the health check failed. The agent can't run turns until this clears.
  • No pill at all — you're connected. Nothing to do.

A slow first turn is normal

Right after launch, Mel checks the relay's health before the first turn; it waits patiently (up to about 30 seconds) before giving up, so a first turn that pauses briefly and then streams is expected behavior, not a bug. If the very first message after launch feels slow, give it half a minute before assuming an outage.

Network checks

The relay exposes an unauthenticated health endpoint. From any terminal:

curl https://<your-relay-host>/health

A healthy relay answers 200 with the plain text ok (see Health & metrics). If that fails:

  • Check your general connectivity (curl https://github.com or similar).
  • Corporate proxies and firewalls that block WebSockets or long-lived connections can break the agent even when normal browsing works — each agent turn is one WebSocket to Mel's server that stays open while the turn runs.
  • If health succeeds but turns fail with a JSON error, that's an application-level problem — see Common errors for what each error means (unauthorized, forbidden, model errors, and friends).

Pointing Mel at a different relay: MEL_RELAY_URL

The relay base URL resolves in this order:

  1. The MEL_RELAY_URL environment variable at runtime (wins over everything). In a release build it must come from your real environment: a .env file in the folder you start Mel from is not read for it (or for MEL_TOKEN), so a project you open cannot point Mel at another server.
  2. The MEL_RELAY_URL baked in at build time (release builds ship with the hosted relay).
  3. The hosted default.

A bare host:port value is upgraded to http://host:port automatically.

Local development

If you're building Mel from source, point it at a local relay:

MEL_RELAY_URL=http://127.0.0.1:7711 cargo run

When the URL is local (127.0.0.1 or localhost) and nothing is answering, Mel auto-spawns a sibling mel-relay binary from the same directory as the app and waits for it to come up — so a local build-and-run works with zero setup. The relay loads its provider keys from its own .env; with no keys configured it returns actionable errors naming the missing key rather than failing silently.

Related