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 — your machine never needs provider keys. 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.

Cold starts are normal

The hosted relay can scale to zero when idle. The first request after a quiet period may take 10–30 seconds while a container spins up; Mel polls the health endpoint 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 agent hi 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 streaming HTTP responses can break the agent even when normal browsing works — the agent stream is long-lived newline-delimited JSON, not a quick request/response.
  • 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).
  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