Maple Harness home

Maple Harness 2.6.2 released! What's new in 2.6.2

Single userTeams & hubs

One person, one machine: the agent, the proxy and your own usage.

Several people, from one shared proxy up to a hub of hubs.

Share Maple with a team: hubs, people and fallbacks #

On this page
  1. In plain words
  2. Who this is for, and who can skip it
  3. The building blocks
  4. A. One shared proxy for a small team
  5. B. Who uses which account
  6. C. Chained hubs
    1. People defined once, at the top
    2. Usage rolls up
  7. D. Fallback across the chain
    1. Your own account first, the team hub when you run out
    2. The hub first, your local model when the hub says no
  8. E. See who used what
  9. F. Day to day: revoking, outages and security
  10. What is not covered, and what is not verified
  11. Related

This guide is for running Maple for more than one person: a small team sharing one proxy, a company with a hub per team, or one person whose laptop should fall back to a shared hub when their own account runs out. It walks through each setup with the configuration to type, what you see afterwards, and where to look when something is not what you expected.

The reference pages hold every key and every flag: Teams for people, teams, tokens, budgets and accounts on one proxy, and Chain proxies into hubs for one proxy using another. This page ties them together. Not sure which setup you need? Which setup do I need? compares them all, from one laptop to several replicas, with what each guarantees and what can go wrong.

In plain words #

  • One proxy, several people: open the proxy to your network, give each person a token, and see who used what. The setup page's People & teams tab walks you through it.
  • Your laptop and a team hub: your own proxy joins the hub, by signing in with your company account or with a token from the hub's admin. Maple Harness keeps talking to your own proxy, as always, and reaches the hub's models through it.
  • Several proxies working as one: a laptop's proxy, a team hub and a company hub can be chained. The upper one hands its people down and receives everyone's usage. The setup page's Hubs & chaining tab does it in two steps: the hub's admin makes a chain token, and you paste it into Connect this proxy to a parent hub. Its hub map then shows every proxy and whether it is still in touch.
  • A fallback across machines: your own account first and the team's when it runs out, or the other way round.

The rest of this page is the technical view: what to type, what you see, and why.

Who this is for, and who can skip it #

If you use Maple on your own machine, you need none of this. Install it, sign in and work, as before. Nothing on this page is on until you add it to config.yaml: a proxy with no people:, no teams: and no other Maple proxy as a provider behaves exactly as it always has, its setup page shows no People or Chained proxies cards, and nothing new appears in your terminal.

Read on if:

  • several people should use one proxy, each with their own token, and you want to see who used what, give each person or team their own accounts, or cap what each can spend;
  • you run more than one proxy (a laptop, a team machine, a company machine) and want them to work as one: people set up once, requests passed up to the machine that holds the accounts, and usage reported back up;
  • you want a fallback that crosses machines: your own account first and the team's when yours runs out, or the team's first and your own local model when the team's is not available.

The building blocks #

WordWhat it is
Proxymaple-proxy: the program that holds sign-ins and keys and talks to the models. Every Maple install has one, usually listening only on 127.0.0.1
HubA proxy that other machines or other proxies use. Nothing extra is installed: a hub is a proxy that listens on a network address and asks every caller for an access token
PersonSomeone who sends requests, named in people: (such as alice). Every request made with one of their tokens counts as theirs
TeamA group of people, named in teams: (such as platform). A team can have accounts, a budget and a model list that its people share
AccountOne provider sign-in or key on a proxy: a GitHub Copilot account, an Anthropic API key, a model server. Each has an id
TokenAn access token made on a proxy, given to one person or one other proxy. config.yaml names a person's tokens by their id, never by the token itself

And two words for chained setups:

WordWhat it is
ParentThe hub a proxy passes requests to: a provider of type: maple, named in chain.parent. A parent can have a parent of its own
ChildA proxy that uses a parent. It inherits the parent's people and teams, and sends its usage records up to it

A. One shared proxy for a small team #

One machine runs the proxy with the team's accounts; everyone else connects to it with their own token.

Three laptops, Alice's with Maple Harness, Bob's with Claude Code and Carol's with OpenCode, each send requests with their own token to one Maple proxy at hub.example. The proxy knows alice and bob are in team platform and carol in team web, and sends requests on to a GitHub Copilot business account, an Anthropic API key or a model server. Its setup page is only reachable on the hub machine.Three laptops, Alice's with Maple Harness, Bob's with Claude Code and Carol's with OpenCode, each send requests with their own token to one Maple proxy at hub.example. The proxy knows alice and bob are in team platform and carol in team web, and sends requests on to a GitHub Copilot business account, an Anthropic API key or a model server. Its setup page is only reachable on the hub machine.
One shared proxy: a token per person, the accounts on one machine.

The hub can run as a program on a machine, as below, in a container (Docker), or on a cluster, with several replicas when a restart must not interrupt anyone (Kubernetes).

1. Open the proxy to the network. On the hub machine, in config.yaml:

server:
  openai_compat: 0.0.0.0:11535
  anthropic_compat: 0.0.0.0:11537
  allowed_hosts: [hub.example]      # the name your teammates use to reach this machine

Off this machine every request needs a token with the proxy scope, and the proxy will not start that way until one exists. List the name your teammates type in allowed_hosts: a request that arrives under another name is refused with 403. The setup page never listens beyond this machine. Reach the hub over HTTPS (in front of the proxy, for example a reverse proxy), or over a private network such as Tailscale or a VPN: plain HTTP across a network others share lets them read the tokens. A hub on the same machine (for a try-out, or a proxy joining a hub that runs beside it) can be reached over plain HTTP, sign-in included, with nothing to set.

2. Make a token for each person, and say whose it is. A person signs in with an access token tied to them; there is no other password. Make each token on the setup page (People & teams, the person's Access and tokens, Make a token: the proxy scope only, tied to them at once), or with maple-proxy token add <label> --person <id>; a token made under Security & access → Remote access is tied on the People card (Edit → Tie a token) or by its id. Every click, how to hand a token over, and what each tool does with it are in How each person signs in.

maple-proxy people add alice --team platform
maple-proxy people add bob --team platform
maple-proxy people add carol --team web
maple-proxy people tie-token alice <token-id>

config.yaml then holds the people with their token ids (never the tokens), and the People card shows each person, their team, their tokens by label and what they spent. The People card applies a change at once, and so does the command when the proxy is running on that machine (it says so); otherwise the proxy reads the change when it next starts. Every step is in Set up a team in four steps.

3. Connect each teammate. A teammate who runs Maple on their own laptop has their own proxy there, and Maple Harness keeps talking to that proxy: their proxy joins the hub, and every tool that uses it (Maple Harness, Claude Code, OpenCode) then reaches the hub's models as hub/<model>. Two ways:

  • Sign in with their company account, when the hub has single sign-on with developer sign-in on. No token to hand over: on their proxy's setup page (Hubs & chaining, Sign in with your company account), with maple-proxy chain connect --sso <the hub's sign-in address>, or with the Maple Harness shortcut maple-harness proxy connect --sso <the hub's sign-in address>, which has their local proxy sign in (the harness itself gets no token). See Join your laptop to a team hub.
  • Paste the token you made for them on their proxy's setup page (Hubs & chaining, Connect this proxy to a parent hub, under Or paste a token from the hub's admin). Test the connection says who the hub counts them as, and the page leaves Use the hub's people and teams here, and send usage up unticked: a person's token uses the hub's models as them, and only a chain token can do more. See Join with a personal token.

Either way the hub counts what their proxy sends as them. Which to choose, and what each guarantees: Which setup do I need?.

Advanced: Maple Harness straight to the hub. Where no proxy of their own can run (a CI job, a container), Maple Harness can use the hub directly: maple-harness proxy connect <address> asks for the token without showing it, keeps it in the secret store and writes only a reference into config.yaml. In a demo setup where the hub is reached by name over plain HTTP, the first try is refused, and the second accepts it:

$ maple-harness proxy connect http://team.example:12835
proxy connect: the proxy at team.example:12835 is on another machine and is reached over plain http, which sends the access token where the network can read it; use https, or a private network such as Tailscale or a VPN and then set harness.proxy.allow_insecure: true if you accept that
$ maple-harness proxy connect --allow-insecure http://team.example:12835
Stored the token in the secret store (file) as maple-proxy-token.
Wrote harness.proxy to /home/demo/bob/.config/maple-harness/config.yaml: url http://team.example:12835, token ${secret:maple-proxy-token}.
Connected: the proxy at http://team.example:12835 accepted the token and serves 2 model(s).
$ maple-harness proxy status
Proxy
proxy:   http://team.example:12835 (run elsewhere)
status:  running, serving 2 model(s)
managed: on its own machine; this harness never starts or stops it

With https:// there is no flag to add. The harness never starts, stops or restarts a proxy on another machine.

Claude Code, OpenCode and other tools use the hub's address and the person's token as their API key: for Claude Code, ANTHROPIC_BASE_URL=https://hub.example:11537 and the token in ANTHROPIC_API_KEY; for OpenCode or any OpenAI-compatible tool, https://hub.example:11535/v1 and the token as the key. See On each teammate's machine.

Each person uses their own token: every request made with one is counted as its person's. A request from the hub machine itself without a token counts as the person local. You are responsible for following each provider's terms for the accounts you connect.

Two of them say who may use a hub's account. Grok (xAI): an API key from your organisation's xAI team, for your organisation's own staff; a hub never uses anyone's Grok subscription. The Gemini API: for your own organisation's people only, and on a paid tier, since Google's free tier may use what is sent to improve its products (see Gemini API). Maple cannot check either for you.

B. Who uses which account #

A hub can hold several accounts for the same models, and give them out: one for everyone, one per team, or one for a single person.

default_accounts: [company]          # tried first for everyone
teams:
  - id: platform
    accounts: [platform-account]     # tried first for the platform team
people:
  - id: bob
    team: platform
    accounts: [bob-account]          # tried first for Bob

The same with the commands:

maple-proxy people default-accounts company
maple-proxy teams accounts platform --accounts platform-account
maple-proxy people accounts bob --accounts bob-account
For a request from bob in team platform, the proxy tries bob's accounts first, then the team's accounts, then the default accounts, then every other account that serves the model, unless accounts_only limits the person to the listed ones.For a request from bob in team platform, the proxy tries bob's accounts first, then the team's accounts, then the default accounts, then every other account that serves the model, unless accounts_only limits the person to the listed ones.
The order the accounts are tried in. An account is only used for models of its own kind.

An account that does not serve the model, or that the person's model list does not allow, is skipped. With accounts_only: true a person or team is limited to their own accounts. The usage log records which account served each request (provider) and why (account_source: person, team, default or request). On a test proxy with a team account and a default account, four requests came out like this:

$ maple-proxy usage query --group-by person,team,provider,account_source --metrics requests
Usage  (all requests)
  PERSON  TEAM      PROVIDER          ACCOUNT_SOURCE  REQUESTS
  alice   platform  copilot-platform  team                   1
  bob     platform  copilot-platform  team                   1
  carol   web       copilot-shared    default                1
  local   -         copilot-shared    default                1
  total                                                      4

Budgets (per person and per team, in AI units, per UTC day and month) and model lists work the same way: see Budgets, Models and Accounts.

C. Chained hubs #

When there is more than one proxy, chain them: each proxy uses the one above it as a provider of type: maple. A laptop goes to a team hub, and the team hub goes to the top hub that holds the company's accounts.

Three Maple proxies in a chain: Alice's laptop, a team hub at team.example and a top hub at top.example that holds the company accounts. Requests go up from the laptop to the team hub to the top hub. People and teams defined at the top hub are handed down to the team hub and the laptop. The team hub adds a person of its own and tightens the platform team's budget; a child may tighten what it inherits, never loosen it.Three Maple proxies in a chain: Alice's laptop, a team hub at team.example and a top hub at top.example that holds the company accounts. Requests go up from the laptop to the team hub to the top hub. People and teams defined at the top hub are handed down to the team hub and the laptop. The team hub adds a person of its own and tightens the platform team's budget; a child may tighten what it inherits, never loosen it.
Requests go up; people and teams come down.

On the setup page (the quickest way): on the hub, Hubs & chaining, Let a proxy connect to this hub, make a chain token for the proxy below; on the proxy below, Hubs & chaining, Connect this proxy to a parent hub, paste the hub's address and the token, Test the connection, Save, and restart it. Step by step, with screenshots, in Chain proxies into hubs. The same with commands and config.yaml:

1. On each hub, make a token for the proxy below it, and list the name the proxy below uses in allowed_hosts:

maple-proxy chain token platform-hub

The token has the proxy and proxy-chain scopes. Only a token with proxy-chain is trusted to say who asked, so a person's own token can never claim to be someone else.

2. On the proxy below, add the hub as a provider and name it as the parent:

server:
  proxy_name: platform-hub           # a readable name in everyone's usage records
providers:
  - id: top
    type: maple
    base_url: https://top.example:11535/v1
    api_key: mh_...                  # the token from maple-proxy chain token
    models:
      - id: claude-sonnet-5
      - id: gpt-5-mini
chain:
  parent: top                        # inherit its people, send usage up to it

Then move the token into the secret store, which leaves a ${secret:...} reference in its place:

maple-proxy secrets migrate

A hub's models are always reachable as <provider id>/<model> (top/claude-sonnet-5). List them under models: on a hub in the middle of a chain: a laptop that asks its hub for hub/claude-sonnet-5 sends the plain name up, and in our test the middle hub answered that the model "is not served by this proxy" (before 2.1.2: "no provider serves model") until the model was listed there. base_url must be https:// unless the hub is on this machine or your local network, or the provider is marked local: true.

3. Check it on the hub map (Hubs & chaining), or with maple-proxy chain status, on any proxy:

The hub map on platform-hub: its parent top-hub above, answers; this proxy with 4 people and 3 teams (5 inherited); below it alice-laptop and design-laptop, each heard just now, with their requests and AI units for the last 7 days.The hub map on platform-hub: its parent top-hub above, answers; this proxy with 4 people and 3 teams (5 inherited); below it alice-laptop and design-laptop, each heard just now, with their requests and AI units for the last 7 days.
The team hub's map: the top hub above, two proxies below. A demo setup with stand-in model services.
This proxy: alice-laptop, id mp-caf79a2b7a80304b; refuses requests that passed
  through more than 4 proxies.

Hubs above:
  hub (parent)
    address:  http://team.example:12835/v1
    answers:  yes (200)
    hub:      platform-hub (mp-f7e3245a0b6c5ff2); hubs above it: 1

People from hub: 4 people, 2 teams, 4 tokens; confirmed 2026-10-09T02:53:52Z.

People defined once, at the top #

Define the people and teams on the top hub. Every proxy below fetches them at start and again as soon as they change (it waits on the hub for news), with their budgets, model lists and accounts, and a check value for each of their tokens, never the tokens. So a person's token made at the top also works at the team hub and on a laptop below it.

A child can add people of its own, and can tighten an inherited entry, never loosen it. On the team hub in our demo:

$ maple-proxy people add dana --team platform
added dana; tie a token with: maple-proxy people tie-token dana <token-id>
$ maple-proxy teams budget platform --monthly 1000
team platform: budget daily no limit, monthly 1000 AI units
$ maple-proxy teams budget web --monthly 900
budget.monthly_ai_units 900.00 would raise the inherited 500.00; a hub may only lower it

A child has to have received its parent's people before it can add its own: until then the command answers "the parent hub's people cannot be read". The People card (on the setup page's People & teams tab) marks inherited entries and offers Tighten instead of Edit:

The People card on the team hub platform-hub, in its People & teams tab: alice, bob and carol are marked from top-hub with a Tighten button each, and dana, added on this hub, has an Edit button. Each row shows the team, today's and this month's AI units and requests; the hub's chain token for alice-laptop is listed apart.The People card on the team hub platform-hub, in its People & teams tab: alice, bob and carol are marked from top-hub with a Tighten button each, and dana, added on this hub, has an Edit button. Each row shows the team, today's and this month's AI units and requests; the hub's chain token for alice-laptop is listed apart.
The team hub's People card: three people from the top hub, one of its own. A demo setup with stand-in model services.

A person added on a child is unknown to the hub above it. There their requests are recorded as name@proxy (dana@platform-hub, team platform@platform-hub), so they can never be taken for, or charged to, one of the hub's own people, and the hub serves them with its own default accounts. Details are in Teams across chained hubs and People and teams cascade down.

Who you are on your own laptop. Your tools on your laptop need no token. Their requests then count as local on the laptop, and as local@alice-laptop on the hubs above. To be counted as yourself everywhere, give your tools your own token from the top hub: it works on every proxy below it.

Usage rolls up #

Each proxy sends its usage records (counts and labels only, never prompts, answers or files) up to its parent, with the records its own children sent it, so the top hub can report on the whole chain. Each request is counted once: every hop shares one request id. If the parent is down, the child keeps its records and sends them when the parent is back. It is on whenever chain.parent is set; chain.report_usage: off turns it off on that child.

Three proxies in a chain. Usage records go up from Alice's laptop to the team hub and from the team hub to the top hub, which reports on its own usage and everything below it by origin proxy. People and teams come down. Records sent up are counts and labels only; each request is counted once; a child keeps its records while the parent is down; chain.report_usage off turns it off.Three proxies in a chain. Usage records go up from Alice's laptop to the team hub and from the team hub to the top hub, which reports on its own usage and everything below it by origin proxy. People and teams come down. Records sent up are counts and labels only; each request is counted once; a child keeps its records while the parent is down; chain.report_usage off turns it off.
Usage goes up, people and teams come down.

The top hub's Hubs & chaining tab draws the tree on its hub map, with each proxy's last seven days, and lists the proxies further below by name:

The hub map on top-hub: this proxy, top-hub, with 3 people and 2 teams and its own requests; below it platform-hub, heard just now, 33 requests and 1.98 AI units.The hub map on top-hub: this proxy, top-hub, with 3 people and 2 teams and its own requests; below it platform-hub, heard just now, 33 requests and 1.98 AI units.
The top hub: one proxy below it, which reports for the two proxies under it (the Table view names them).

The same tab charts the whole tree's requests and spend, and its Chained proxies card shows the proxies below it and what they reported, counting each request once by default (All hops counts a line per proxy instead):

The Chained proxies card on top-hub: one proxy below, platform-hub, with its last report and size; a table by source shows 25 client requests and 1.98 AI units from the child and 4 client requests and 6.93 AI units recorded locally, 29 in total and 8.91 AI units.The Chained proxies card on top-hub: one proxy below, platform-hub, with its last report and size; a table by source shows 25 client requests and 1.98 AI units from the child and 4 client requests and 6.93 AI units recorded locally, 29 in total and 8.91 AI units.
The top hub: its own requests, and everything the proxies below sent up. A demo setup with stand-in model services.
The Chained proxies card on platform-hub after Check now: its parent top answers, its people and teams from top are up to date (3 people, 2 teams, 3 tokens), 37 usage lines were sent to the parent with nothing waiting, one proxy below it, alice-laptop, reported 17 client requests, and the parent hub settings.The Chained proxies card on platform-hub after Check now: its parent top answers, its people and teams from top are up to date (3 people, 2 teams, 3 tokens), 37 usage lines were sent to the parent with nothing waiting, one proxy below it, alice-laptop, reported 17 client requests, and the parent hub settings.
The team hub: its hub above, the people it inherited, what it sent up, and the laptop below it.

D. Fallback across the chain #

The pattern most people want from a chain is a fallback that crosses machines, either way round. Both are ordinary fallbacks on the proxy where you set them, so they work on any proxy in the chain.

Two fallback orders on Alice's laptop proxy. Left: her own Copilot account first, then the team hub if it is out of credits or rate limited. Right: the team hub first, then a local model on her laptop if the hub refuses, is over budget or is unreachable.Two fallback orders on Alice's laptop proxy. Left: her own Copilot account first, then the team hub if it is out of credits or rate limited. Right: the team hub first, then a local model on her laptop if the hub refuses, is over budget or is unreachable.
Your account first, or the hub first.

Your own account first, the team hub when you run out #

On your laptop: your own Copilot account serves your requests, and when it is out of credits or rate limited they go to the team hub, for the same model.

providers:
  - id: hub
    type: maple
    base_url: https://team.example:11535/v1
    api_key: ${secret:hub-token}
  - id: copilot
    type: github-copilot             # as set up by maple-proxy auth login github-copilot
chain:
  parent: hub
provider_fallbacks:
  copilot: [hub]                     # or [hub/<model>] for a different model at the hub

While your account is marked as out of quota, later requests go straight to the hub (the route reason is exhausted-order), and back to your account once its wait is over. The answer says what happened:

X-Maple-Fallback-From: copilot/claude-sonnet-5 (quota exhausted)
X-Maple-Router: via hub: top/claude-sonnet-5 [via top: copilot-company/claude-sonnet-5]
X-Maple-Served-By: hub/claude-sonnet-5

The hub first, your local model when the hub says no #

Everything goes to the hub, and a model on your own machine answers when the hub refuses (a budget there is spent, its accounts are out of quota) or cannot be reached:

providers:
  - id: hub
    type: maple
    base_url: https://team.example:11535/v1
    api_key: ${secret:hub-token}
  - id: ollama
    type: ollama
    base_url: http://127.0.0.1:11434/v1
    models: [{id: qwen3-coder}]
provider_fallbacks:
  hub: [ollama/qwen3-coder]

With the team hub stopped, the answer came from the local model:

X-Maple-Fallback-From: hub/claude-sonnet-5 (unreachable)
X-Maple-Served-By: local/qwen3-coder

and with the top hub's account out of quota, two hubs up, the same:

X-Maple-Fallback-From: hub/claude-sonnet-5 (quota exhausted)
X-Maple-Served-By: local/qwen3-coder

Both can be set on one laptop, as in the demo below. model_fallbacks works too, for one model at a time; see The two common setups and Fallbacks. The usage log says why each fallback ran:

usage query for person alice grouped by route reason and provider: copilot 7 requests direct, hub 5 direct, exhausted-order hub 3 with 3 fallbacks, fallback:unreachable local 2 with 2 fallbacks, fallback:quota-exhausted hub 1 with 1 fallback, 18 in total with 6 fallbacks.usage query for person alice grouped by route reason and provider: copilot 7 requests direct, hub 5 direct, exhausted-order hub 3 with 3 fallbacks, fallback:unreachable local 2 with 2 fallbacks, fallback:quota-exhausted hub 1 with 1 fallback, 18 in total with 6 fallbacks.
Alice's laptop: her own account until it ran out, then the hub, and her local model while the hub was stopped. A failed try is its own line.

E. See who used what #

Every proxy in the chain records, on each request, who asked (person, team), which proxy they asked (origin_proxy), the path (via, hops), the account that served it and why (provider, account_source, route_reason). Filter by any of them on the setup page, with maple-proxy usage query, or in DuckDB.

On the setup page, the filter bar above the data tabs offers Person, Team, Origin proxy, Proxy and Account source once there are two values to choose between, and every card follows it. Here the top hub shows only the platform team's requests that started on Alice's laptop:

The setup page's range buttons on 7 days and the filter bar with Filters (2): Team set to platform and Origin proxy set to alice-laptop, the others on Any.The setup page's range buttons on 7 days and the filter bar with Filters (2): Team set to platform and Origin proxy set to alice-laptop, the others on Any.
The filter bar, filtered by team and by the proxy the requests started on.
The top hub's Chained proxies card for that filter: 15 client requests from the child and 4.29 AI units in total, 1.98 spent below and 2.31 at the top hub.The top hub's Chained proxies card for that filter: 15 client requests from the child and 4.29 AI units in total, 1.98 spent below and 2.31 at the top hub.
The same filter on the Chained proxies card: Alice's 15 requests, and the AI units spent at each end.
The top hub's Hubs & chaining tab charts for that filter: client requests per day by the proxy they first reached (alice-laptop, 15 today), and AI units spent by proxy: 2 at alice-laptop, 0 at platform-hub, 2.3 at top-hubThe top hub's Hubs & chaining tab charts for that filter: client requests per day by the proxy they first reached (alice-laptop, 15 today), and AI units spent by proxy: 2 at alice-laptop, 0 at platform-hub, 2.3 at top-hub
The Hubs & chaining tab's charts for the same filter.

With usage query on the top hub, for the whole chain:

usage query on the top hub grouped by origin proxy, person and team: alice-laptop alice platform 15 client requests, 32 requests, 4.29 AI units spent; platform-hub bob platform 5, 10, 1.65; alice-laptop local@alice-laptop 0, 4, 0.66; top-hub carol web 4, 4, 1.32; platform-hub dana platform 3, 3, 0; platform-hub dana@platform-hub 0, 3, 0.99; alice-laptop local 2, 2, 0; total 29 client requests, 58 requests, 8.91 AI units.usage query on the top hub grouped by origin proxy, person and team: alice-laptop alice platform 15 client requests, 32 requests, 4.29 AI units spent; platform-hub bob platform 5, 10, 1.65; alice-laptop local@alice-laptop 0, 4, 0.66; top-hub carol web 4, 4, 1.32; platform-hub dana platform 3, 3, 0; platform-hub dana@platform-hub 0, 3, 0.99; alice-laptop local 2, 2, 0; total 29 client requests, 58 requests, 8.91 AI units.
Who asked where, across three proxies. client_requests counts each request once; requests counts a line per proxy it passed through. People the top hub does not know (dana, added on the team hub, and Alice's tools without a token) appear twice here: under the child's name where the request started, and as name@proxy on the top hub's own line, where the AI units were spent. The maple.origins view below puts them together.
maple-proxy usage query --last 7d --group-by origin_proxy,person
maple-proxy usage query --team platform --group-by person,provider,account_source
maple-proxy usage query --person alice --group-by route_reason,provider
maple-proxy usage query --proxy alice-laptop --source child     # only what a proxy below sent up

In DuckDB, maple-proxy usage schema --format sql --views makes the named views, including maple.people, maple.daily_spend, maple.origins (per first proxy and person, each request once) and maple.proxies (per proxy):

A DuckDB session on the top hub: maple.origins lists alice-laptop alice 15 client requests 4.29 AI units, platform-hub bob 5 and 1.65, top-hub carol 4 and 1.32, platform-hub dana 3 and 0.99, alice-laptop local 2 and 0.66; maple.proxies lists alice-laptop child 20 lines and 17 client requests, platform-hub child 17 lines, top-hub local 21 lines; maple.daily_spend by account lists company 9 requests 2.97 AI units, platform-account 7 and 2.31, bob-account 5 and 1.65.A DuckDB session on the top hub: maple.origins lists alice-laptop alice 15 client requests 4.29 AI units, platform-hub bob 5 and 1.65, top-hub carol 4 and 1.32, platform-hub dana 3 and 0.99, alice-laptop local 2 and 0.66; maple.proxies lists alice-laptop child 20 lines and 17 client requests, platform-hub child 17 lines, top-hub local 21 lines; maple.daily_spend by account lists company 9 requests 2.97 AI units, platform-account 7 and 2.31, bob-account 5 and 1.65.
Per person and origin, per proxy, and per account on the top hub.
SELECT person, team, requests, round(ai_units, 2) AS ai_units, origin_proxies FROM maple.people ORDER BY ai_units DESC;
SELECT origin_proxy, person, team, client_requests, round(ai_units_spent, 2) AS ai_units FROM maple.origins ORDER BY 5 DESC;
SELECT provider AS account, sum(requests) AS requests, round(sum(ai_units), 2) AS ai_units FROM maple.daily_spend GROUP BY ALL ORDER BY 3 DESC;

All figures are AI units as the providers reported them, or estimates labelled _estimated; neither is a bill. More queries are in See and filter your usage and Named views.

To keep the whole chain's history past the top hub's retention, give the top hub a lake: its own lines and the ones sent up from below go into it together (Hubs: every proxy's data in one lake).

F. Day to day: revoking, outages and security #

Revoking someone. Revoke their token on the proxy that made it (the setup page's token list). It stops working there at once, and on every proxy below within seconds while the hubs answer, one hop after another (a proxy below that cannot reach its hub keeps the last copy for up to chain.directory_grace, 15 minutes by default). To stop a whole proxy below, revoke its chain token on its hub (Hubs & chaining, the token's Revoke); when a proxy below is replaced, Unbind its token so the new one can use it.

Watching the chain. The hub map marks a proxy below that has not asked its hub for five minutes (it asks at least every minute while it runs), so a stopped laptop or a broken network shows up without anyone reporting it. Removing a person from people: stops their budget and rules applying; revoking the token is what stops the requests.

When a parent hub is unreachable:

  • requests that have a fallback set go to it (see D); requests without one fail with unreachable;
  • the child keeps using the people it fetched last for chain.directory_grace (15 minutes by default); after that it refuses the inherited tokens until the parent answers again, and keeps serving its own people;
  • usage records wait on the child and are sent when the parent is back, never counted twice. In the demo, the two requests made while the team hub was stopped reached the top hub's figures once it was running again.

Security, in short:

  • Reach a hub over HTTPS, or over a private network such as Tailscale or a VPN. The tokens travel with every request.
  • One token per person and per proxy below, never shared. Treat tokens like passwords; Maple keeps them in your secret store and writes only references into config.yaml.
  • The setup page stays on its own machine: signing in to providers, the People card, chain tokens and connecting to a hub are only there. Through single sign-on, team admins see the hub map without addresses or tokens.
  • Only a token with the proxy-chain scope may say who asked. Give it only to proxies you run.
  • More in Security.

What is not covered, and what is not verified #

  • Downgrading. A proxy older than 2.0 ignores people:, teams: and default_accounts: and keeps working, but no budget, model list or account rule applies and requests are no longer attributed (see Going back to an older version). A chain was not tested with an older proxy in it.
  • Older usage. Requests from before 2.0, or before people were set up, are unattributed: person is empty and origin_proxy unknown.
  • Not verified: the screenshots and outputs on this page come from a demo on one Linux machine, with three proxies on loopback reached by name over plain HTTP, and stand-in model services in place of Copilot and the other providers. Chains over HTTPS between machines, with real GitHub Copilot accounts, and on macOS or Windows, have not been tried yet.

Made with ❤️ by Kinn Coelho Juliao in Ottawa, eh — fuelled by double-doubles, bud. 🍁