Skip to content
Cetas

Connecting the Magpie gateway

From starting the gateway to one real inference — which two settings to change, where the credential goes, how to switch managers, what each step should show, and where to look when it fails.

Magpie is a model gateway that runs on your machine or inside your network: models, accounts, and keys are managed on the gateway side, and Cetas only has to connect, pick a model, and get to work.

The support is native: /manager switches between the provider set and Magpie, /model picks the conversation model and its reasoning effort, /quota reads quota, /status reports gateway and catalog state, and /login writes the credential into the shared credential store. This page walks one line from end to end: start the gateway → let Cetas connect → switch manager → pick a model → verify it works. Every step says what you must see before it counts as done.

1. Start the gateway and confirm it is alive

The Magpie gateway is a separate process, at http://127.0.0.1:3425 by default. Its installation, deployment, and operations follow Magpie’s own documentation; this page only establishes one thing: Cetas can see it.

Two shapes, with different prerequisites:

  • Local gateway: bound to a loopback address. Cetas authenticates with its built-in local application token (Authorization: Bearer magpie-posoco), so you do not prepare a key.
  • Remote gateway: needs a gateway key, and the address must be an HTTPS origin or a loopback HTTP origin; anything else is refused on the Cetas side: gateway must be an HTTPS origin or loopback HTTP origin.

Success marker: curl http://127.0.0.1:3425/api/hello returns a JSON object whose "name" is "magpie", and curl http://127.0.0.1:3425/v1/models returns JSON with a data array. Those are exactly the two endpoints Cetas probes when it refreshes the catalog; an answer whose name is not magpie is never accepted.

If the gateway itself demands authentication, curl needs the same Bearer token; in that case treat the /status in step 5 as the authority.

2. Let Cetas connect: settings and credential

The address and the credential are two different things, stored in two different places. This step has two halves: first make the address usable, then make the credential usable — each half has its own success marker, in the two subsections below.

What Where it lives Who writes it
magpie.base_url, magpie.enabled <CETAS_HOME>/.cetas/settings.json /login magpie writes it; you may also write it by hand
The gateway credential The shared credential store (<CETAS_HOME>/.cetas/credentials/) Only /login magpie 
/login magpie

First pick the gateway shape: Local Gateway (http://127.0.0.1:3425) or Remote Gateway (HTTPS with Gateway Key). The remote path asks two more things: Gateway HTTPS origin and Gateway Key (input hidden).

This step does more than write configuration: it really connects to the gateway once — reading /api/hello, then /v1/models.

Success marker: Magpie Gateway verified and configured.

The failure is a single line and deliberately says nothing specific: /login magpie cancelled, unavailable or invalid — cancelling, an unreachable gateway, a wrong key, and an unsafe address all land there. See the last section for triage. While a turn is running it refuses up front: /login magpie requires an idle application.

/login magpie writes magpie.base_url and magpie.enabled: true, and does not write model_manager. It only settles “can Cetas connect”; whether to switch is the next step.

Or write settings.json by hand

{
  "model_manager": "magpie",
  "magpie": {
    "base_url": "http://127.0.0.1:3425",
    "enabled": true
  }
}
  • magpie.base_url is an origin: no path, query, or userinfo. http://127.0.0.1:3425/v1 is rejected with base_url must be a gateway origin without path, query or userinfo; a missing http(s):// is rejected with base_url must be an absolute http(s) URL.
  • magpie.enabled must be a boolean. The string "true" is not accepted leniently — composition fails outright: settings.magpie.enabled must be a boolean.
  • model and reasoning_effort can be written together as the startup selection; reasoning_effort on its own is rejected with selected_effort is set without selected_model.

Success marker: model_manager and magpie are both present, base_url is a bare origin, and enabled is a bare true / false.

The credential goes only into the shared credential store

The gateway key does not belong in settings.json. There is exactly one source for the credential: the copy /login magpie writes into the shared credential store. Whatever is written into settings.json is not used.

A magpie.gateway_key inside the magpie section is ignored, and Cetas warns about it, with this exact text:

settings.json magpie.gateway_key is ignored; store the gateway credential with the shared credential store (provider id 'magpie') instead of editable configuration.

A gateway_key written on the providers entry whose id is magpie is no help either: that is not the credential’s entry point, nothing reads it, and the credential still comes only from the store.

Success marker: searching settings.json finds no key; the key came from /login magpie and lives in the credential store.

3. Switch to the Magpie manager

/manager

Select model manager offers Providers or Magpie. Switching recomposes the agent on the new manager, so it needs an idle application — mid-turn it answers /manager requires an idle application.

Success marker: model manager: magpie, and the manager label next to the model name on the status bar changes from Posoco to Magpie.

Two side effects worth knowing up front:

  • The Board service stops (if it was open): Board service stopped because the model manager switched to magpie. Reopen it with /board.
  • The choice is recorded: model_manager remembers the active manager, manager_selections remembers the model and effort each manager last used, and switching back restores them without re-picking.

4. Pick a model and a reasoning effort

/model

The list is the gateway’s /v1/models, grouped under magpie (the gateway’s routing groups get their own group); after picking, use the left/right keys to choose a reasoning effort.

Success marker: selected <model-id> at effort <effort> (pending=false).

pending=true is a different signal: the model recorded in settings is not in the current catalog, and the line continues with (selection '<model-id>' is pending: not in the catalog yet; requests will fail until a refresh provides it). Pick another one with /model, or refresh the catalog as in step 6.

The decision slot is a provider-set account: the model /decision chose stays in decision_model, is left untouched while Magpie is active, and applies again when you switch back — no re-picking.

5. Verify three things

All three must pass before this line counts as walked: gateway state, quota, and one real inference. Each has its own success marker.

/status: gateway, selection, and catalog in one line

/status

Under the Magpie manager, /status is answered by the gateway extension, and its first line is plain language:

/status: connected to magpie <version>; selected <model-id> at effort <effort> (pending=false); <N> models; services: Route=Unknown Quotas=Unknown Limit=Unknown Usage=Unknown UsageRequests=Unknown Concurrency=Unknown

Success marker: the line starts with connected to magpie, and <N> models is not 0.

The other possibilities on that line are exactly your triage entries:

  • gateway offline: followed by the reason — the gateway is unreachable;
  • authentication failed: followed by the reason (for example /api/hello answered HTTP 401 or 403) — the credential is wrong;
  • invalid gateway response: followed by the reason — the endpoint is not Magpie, or the address points elsewhere;
  • disabled: the manager is configured with enabled = false — the manager is switched off;
  • not connected: no refresh has run yet — no catalog refresh has succeeded yet.

services: reports the availability of each observability endpoint (Unknown, Accessible, Forbidden, NotSupported, TemporarilyUnavailable); one you never called reads Unknown. A structured summary of the same facts follows the line.

/quota: quota is readable

/quota

Success marker: a Quotas panel listing the quota cards the gateway reports — provider, account or plan, and each window’s remaining amount and reset time. To force a re-read from the gateway, use /quota refresh.

An unreadable quota says so explicitly: with no accessible card at all it is No accessible quota cards.; when the gateway refuses the call, /quota answers Magpie quota unavailable or forbidden. A failed quota read does not affect inference.

Run one real turn

Ask anything.

Success marker: a streamed reply arrives, and the selected in /status is the model you just picked.

6. Troubleshooting

Read the /status line first; it already states the conclusion.

Symptom Most likely cause What to do
/status says gateway offline: followed by the reason; /login magpie keeps failing The gateway is not running or unreachable, the port is wrong, or a firewall blocks it Go back to step 1, check the process and the port, probe /api/hello with curl; if the port is not 3425, correct magpie.base_url
/status says invalid gateway response: followed by the reason base_url is wrong: it points at another service, was written with a path, or the gateway identity does not match (/api/hello returns a name that is not magpie) Write base_url as an origin only (http://127.0.0.1:3425), then re-verify with /login magpie
/status says authentication failed: followed by the reason; a remote gateway never connects The credential is missing or wrong /login magpie → Remote Gateway, re-enter the Gateway Key; also confirm the gateway_key in settings.json sits in the right place — in the wrong place it only warns and never takes effect
Startup or the switch fails outright, with settings.model_manager must be providers or magpie, settings.magpie.enabled must be a boolean, or settings.magpie.base_url must be a string in the error A setting has the wrong type Fix it to the strict values in the Settings reference: model_manager is only providers or magpie, magpie.enabled is only a boolean. A plausible-looking string is not accepted
/model does not show a model the gateway just added The catalog is read at agent startup and on manual refresh; there is no background polling under the Magpie manager Run /magpie_refresh; success is catalog refreshed: <N> models
/status says disabled: … magpie.enabled is false Set it back to true, or run /login magpie again

An unreachable gateway does not prevent Cetas from starting: the session comes up normally, /status honestly reports offline, and /model answers Model catalog unavailable.

The complete lists of commands and settings are in Commands and the Settings reference.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close