Docs · Sharing

Remote magpie

One magpie can serve several computers. Sign in and set up providers and routing groups once, on the computer that keeps them (your desktop, a server, a NAS in Docker), and on every other computer add that magpie as a provider of its own: a Remote magpie.

	The shared magpie	Each other computer’s magpie
Providers, subscriptions, keys	kept and signed in here	uses them through the Remote magpie
Routing groups	made here	picked as `office/group/…`
Agents	its own	still wired by this computer’s magpie
Usage and quotas	counted and read here	shown here, named with the remote

The computer you sit at still runs magpie: it wires that computer’s agents, picks their models and keeps their sessions. Only the models come from the other one.

Turn on sharingOn the computer that keeps your providers: Settings → Network and sharing → Share on local network → On. magpie then listens on the local network and makes a gateway key named Magpie. The Address row below the switch shows where other computers reach it, such as http://192.168.1.20:3425.
Make a key for each computerGateway → Gateway keys, or magpie gateway-key add "Laptop", which prints its sk-magpie-key-…. Each key can have its own daily, weekly or monthly limit and its own models, and its calls are counted under its name.

While sharing is off, a desktop magpie listens on its own computer only, and other computers can’t reach it. A magpie in Docker is reached through its published port instead, and asks every caller outside its container for a gateway key, shared or not; see Docker.

2. Add it on the other computer

You need the address and a key from step 1. Any of these does it:

The app: on the Providers tab press ＋ Add provider, pick Remote magpie under Another computer’s magpie (the last heading), then give its address and the key.
The TUI (magpie tui): on the Providers page press a, pick Remote magpie, then type its address and key. On its row, w changes the address and m fetches its list again.
The CLI:

Shell

magpie provider add remote-magpie sk-magpie-key-… url=http://192.168.1.20:3425 id=office
magpie models            # office/… are the shared magpie's
magpie provider refresh office   # fetch its list again

id= names the provider here, and so begins its models’ ids (office/…). The address can be typed as 192.168.1.20:3425 (plain http:// is assumed), with /v1 after it, or as the root: magpie puts every API on it either way. Add one Remote magpie for each computer you share from, with a different id.

What you get

Its models, as its own agents are shown them: office/relay-a/claude-sonnet-5, labelled Claude Sonnet 5 · Relay A · office. The ids stay ids; only the labels carry the names. Pick them for an agent here like any other model.
Its routing groups, as office/group/…. The group decides on the shared magpie, with its accounts.
Every API. A request goes on in the API the agent spoke (Anthropic Messages and token counting, Responses, Chat Completions). A model that the shared magpie’s provider serves on another API only is turned into that API once, never on both computers. Responses go over HTTP, SSE included, not WebSocket.
Images and video. Its image and video models are found by themselves and served through its image generation and edit, and video, APIs.
System One. Its decision models (Jev, Clef, and models with names of your own) are set up at its /v1/systemone and appear as decision models, not chat models. Refresh the provider’s list to find new ones. A bare office asks the first decision model listed.
Embeddings, rerank, speech to text and text to speech go to its matching APIs. They stay in agents’ lists as they are on the remote; being listed doesn’t make them able to hold a conversation.
Prices. Each model costs here what the shared magpie counts it at (a price set there by hand, else its provider’s list price), so the two computers count the same. A price you set here comes first.

Quotas and usage

The Usage page, the menu bar and magpie quota show the shared magpie’s subscription cards, named with it (Codex · office, id office/codex), as that magpie last read them: only the computer with the sign-ins asks the vendors. A card’s refresh here has it read that card once more, at most once every 30 seconds. A Codex reset or a WorkBuddy check-in is pressed on that computer, from its own app, TUI or CLI. A key that magpie holds to a budget, some models or some accounts is told none of its cards: only that key’s own card shows here, with its limit.

The shared magpie counts this computer’s requests under the name of the gateway key it sends, with the account that answered.

Short-lived keys

A program that starts agents in sandboxes can give each one a gateway key of its own that stops working by itself. The key lives 1 minute to 30 days, and may be held to some models, some accounts, a number of tokens or a cost over its whole life, or to read-only use. Its secret is told once, in the answer.

Shell

curl -s -X POST http://127.0.0.1:3425/v1/magpie/keys \
  -d '{"name":"sandbox-1","ttl":"1h","models":["office/codex/gpt-5"],"tokens":200000}'
# {"id":"k…","name":"sandbox-1","key":"sk-magpie-…","expires":"…","models":[…],"limit":{…}}
curl -s http://127.0.0.1:3425/v1/magpie/keys              # the keys you issued, masked
curl -s -X DELETE http://127.0.0.1:3425/v1/magpie/keys/k…  # revoke one early

A program on this computer may call it with no key; a page in a browser may not. Another computer, a container or CI calls it with a gateway key you let issue keys, and every key it issues is held to that key: never a model or account it may not use, never past its own expiry, and what they spend counts against its limit. Turning it off or removing it stops its keys at once. The same from the command line, which prints the key alone:

Shell

magpie gateway-key issue --ttl 1h --name sandbox-1 --models office/codex/gpt-5 --tokens 200000
magpie gateway-key issuer <id> on    # let a key issue keys
magpie gateway-key issue --ttl 30m --from <id> --read-only --json
magpie gateway-key list               # until 10-31 14:00, expired, issued by …

An expired key is refused with 401 and why (“the gateway key "sandbox-1" expired at …: ask for a new one”) on every API, from this computer too. It is removed an hour later.

Keys for GitHub Actions

A GitHub Actions job can get a short-lived key without a gateway key in the repository’s secrets: it trades the OIDC token GitHub gives it. Write a rule naming the repository (and, if you like, the branch, environment or any other claim, exact or with *), the gateway key its keys are issued under, and how long they live:

Shell

magpie gateway-key issuer <id> on
magpie gateway-key oidc add --key <id> --repo owner/app --ref refs/heads/main --ttl 1h
# prints the rule id and its audience, magpie-<rule id>
magpie gateway-key oidc list
magpie gateway-key oidc remove <rule id>

In the workflow, ask GitHub for a token with the rule’s audience and POST it to /v1/magpie/keys/oidc:

YAML

permissions:
  id-token: write
steps:
  - name: Get a magpie key
    run: |
      TOKEN=$(curl -s -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
        "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=magpie-<rule id>" | jq -r .value)
      KEY=$(curl -s -X POST https://<your magpie>/v1/magpie/keys/oidc \
        -H "Authorization: Bearer $TOKEN" -d '{"ttl":"30m"}' | jq -r .key)
      echo "::add-mask::$KEY"
      echo "MAGPIE_KEY=$KEY" >> "$GITHUB_ENV"

The key is issued under the rule’s gateway key and held to it like any other issued key, lives no longer than the rule says, and is named after the repository, branch and run. A token from another repository or branch, an expired one, or one already traded gets 401 and why. The route answers another computer only while magpie is shared, and refused tokens count against the failed sign-ins it allows. Without a rule nothing is traded.

Stats API

What the Usage page shows is also served as JSON, to this computer and, while magpie is shared, to a request with a gateway key. A key held to a budget, models or accounts is told only its own calls and limit.

/v1/magpie/usage?period=today|7d|30d|all: totals, by model, agent, provider, account and gateway key.
/v1/magpie/usage/requests: the request log, with period, day, offset, limit, and filters model, agent, provider, account, callerKey, failed=1, retried=1 and q.
/v1/magpie/quotas: each subscription’s windows (?kept=1 without asking the vendors); /v1/magpie/quotas/history?days=: what was left over time, 45 days at most.
/v1/magpie/limit: the key’s own limits, its expiry, and its issuer’s limits.
/v1/magpie/concurrency: requests in flight, per account.

Shell

curl -s 'http://127.0.0.1:3425/v1/magpie/usage?period=7d'
curl -s 'http://127.0.0.1:3425/v1/magpie/usage/requests?period=today&callerKey=k…&failed=1&limit=50'
curl -s 'http://127.0.0.1:3425/v1/magpie/quotas?kept=1'
curl -s 'http://127.0.0.1:3425/v1/magpie/quotas/history?days=14'
curl -s http://127.0.0.1:3425/v1/magpie/limit -H 'Authorization: Bearer sk-magpie-…'
curl -s http://127.0.0.1:3425/v1/magpie/concurrency

When it doesn’t work

You see	What to do
“magpie isn’t shared on the local network”, or “remote magpie isn’t shared”	turn on Share on local network on that computer
“remote magpie didn’t take this key” (401)	use one of its enabled gateway keys: Gateway → Gateway keys there
403 for a model	that key may use only some models: `magpie gateway-key models <id>` on that computer shows or changes them. A bare `office` asks System One’s first decision model, whatever the key allows; use the full `office/provider/model` id
“couldn’t reach the remote magpie”	check the address, that magpie is running there with sharing on, and that its firewall lets the port in
no System One models, or “doesn’t share its quotas”	update magpie on that computer, then refresh the list here

Away from home, reach the shared magpie over a VPN such as Tailscale or WireGuard, with its address there. Don’t open its port to the internet.

Questions or a setup worth sharing? Ask on Discord. The reference has the details.