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.

Which setup do I need? #

On this page
  1. In plain words
  2. At a glance
  3. Words used on these pages
  4. 1. One laptop
  5. 2. Your laptop's proxy joined to a team hub
  6. 3. A team hub for many people
  7. 4. Hubs chained to a company hub
  8. 5. Several replicas behind a load balancer
  9. 6. CI jobs and containers
    1. GitHub Actions: start the proxy in the job
    2. GitHub Actions: a proxy in a service container
    3. When a run does not start
  10. How to move between setups
  11. What is not verified
  12. Related

Maple runs the same way on one laptop and in a company: a proxy holds the accounts and talks to the models, and your tools talk to a proxy. The setups below differ only in how many proxies there are and how they are joined. Start with the first one that fits, and move to another later: nothing you set up is lost (see How to move between setups).

In plain words #

Answer three questions:

  1. Is it just you? Then use one laptop. Install it, sign in, work. Nothing on this page is needed, and nothing here shows up until you set it up.
  2. Does your company or team already run a Maple hub? Then join your laptop's proxy to it: sign in with your company account (about a minute), or paste a token the hub's admin gives you. Maple Harness keeps working exactly as before; it now also reaches the hub's models.
  3. Are you the one setting up the hub? Then pick by size:

And for a CI job, a script or a container, see CI and containers: start the proxy in the job, and nothing needs setting.

These combine: a company hub can run as several replicas, with single sign-on, a team hub chained below it, and laptops signed in to the team hub.

At a glance #

SetupPick this ifWhat you runStep by step
1. One laptopYou use Maple on your ownmaple-harness (it starts maple-proxy for you)Your first session
2. Laptop joined to a hubYour team runs a hub and you want its models, budget and accountsYour own proxy, signed in to the hubJoin your laptop to a team hub
3. A team hubSeveral people should share accounts, with a token, a budget and a model list eachOne maple-proxy on a machine the team reachesShare Maple with a team
4. Chained hubsSeveral teams, each with its own hub, and one place for people and usageA proxy per team, joined to a company hub with a chain tokenConnect a team proxy with a chain token
5. Several replicasA hub must not stop for a restart or a lost machineCopies of one proxy behind a load balancer, with PostgreSQL and RedisKubernetes or Docker
6. CI and containersA CI job, script or container runs Maple Harness with nobody to answerThe proxy started in the job; or maple-harness with a token, or with trust_uncheckedGitHub Actions: start the proxy in the job

Words used on these pages #

WordWhat it means
Proxymaple-proxy, the program that holds sign-ins and keys and talks to the models. Every Maple install has one
HubA proxy that other machines or other proxies use. Nothing extra is installed: a hub is a proxy that listens on the network and asks every caller for a token
Personal tokenAn access token that belongs to one person. Everything sent with it counts as that person. Your proxy gets one when it signs in with your company account; an admin can also make one for you, or you make one on the hub's My access page
Chain tokenA token the hub's admin makes for one proxy that serves many people. It lets that proxy bring the hub's people down, send its usage up, and say who asked for each request
Sign-in addressThe hub's single sign-on address, such as https://maple-admin.example.com, where people sign in with their company account. It is not the address of the hub's models
Parent hubThe hub a proxy joined with a chain token (chain.parent). A hub you signed in to with your company account is never a parent

1. One laptop #

Maple Harness, Claude Code and OpenCode on your laptop send requests to the maple-proxy on the same laptop at 127.0.0.1, with no token. The proxy holds your sign-ins and keys and sends requests on to your GitHub Copilot account, an Anthropic API key or a model server. Its setup page is on the laptop only.Maple Harness, Claude Code and OpenCode on your laptop send requests to the maple-proxy on the same laptop at 127.0.0.1, with no token. The proxy holds your sign-ins and keys and sends requests on to your GitHub Copilot account, an Anthropic API key or a model server. Its setup page is on the laptop only.
One laptop: your tools, your proxy, your accounts.

Pick this if you use Maple on your own. This is the setup everyone starts with, and most people stay with.

What you run. maple-harness. It starts maple-proxy on the same machine when nothing is running, and you sign in to your accounts on the proxy's setup page (http://127.0.0.1:11539). Claude Code, OpenCode and other tools on the same machine can use the same proxy without a token (Use your models from other tools).

What it guarantees.

  • The proxy listens only on this machine (127.0.0.1), and its setup page refuses to listen anywhere else.
  • Maple Harness checks, on every connection, that the proxy it talks to is your own, with a key only you can read (Verified and unverified proxies).
  • Your keys stay in your system keyring or secret store; config.yaml holds only references.
  • No people, teams, hubs or tokens appear anywhere until you set them up.

What can go wrong, and how you see it.

What happensHow you see itWhat to do
The proxy is still the old release after an updateBefore a session: "Your proxy at … is an older release than this harness", with [r] restartPress r, or maple-harness proxy restart
The proxy runs as another user, in a container, or with another settings folder"You're connecting to an unverified proxy at …"; tools ask before every runHow to fix it
Another program holds the proxy's port"something else is answering on <address>, not your Maple proxy"Stop that program, or move the proxy's ports in server:
An account is out of credits or rate limitedThe request fails with that reason, and Provider health on the setup page shows itAdd a fallback (Fallbacks)

Step by step: Install, then Your first session and Sign in.

2. Your laptop's proxy joined to a team hub #

On your laptop, Maple Harness, Claude Code and OpenCode keep talking to the maple-proxy on the laptop. That proxy is joined to the team hub at hub.example, signed in with your company account or holding a token from the hub's admin. The hub counts what your proxy sends as you and sends it on to the company's accounts.On your laptop, Maple Harness, Claude Code and OpenCode keep talking to the maple-proxy on the laptop. That proxy is joined to the team hub at hub.example, signed in with your company account or holding a token from the hub's admin. The hub counts what your proxy sends as you and sends it on to the company's accounts.
Your tools keep using your own proxy; your proxy uses the hub, as you.

Pick this if your team or company runs a Maple hub and you want its models, under your own name, budget and model list.

What you run. Nothing new. Your own proxy joins the hub, and Maple Harness keeps talking to your own proxy, as on one laptop. Every tool that uses your proxy (Maple Harness, Claude Code, OpenCode) then reaches the hub's models as hub/<model>, next to your own accounts if you keep any. There are two ways to join:

Sign in with your company account (recommended)Paste a personal token from the hub's admin
WhenThe hub has single sign-on with developer sign-in onAny hub, with or without single sign-on
HowYour proxy's setup page (Hubs & chaining, Sign in with your company account), maple-proxy chain connect --sso <sign-in address>, or the shortcut maple-harness proxy connect --sso <sign-in address>Your proxy's setup page (Hubs & chaining, Connect this proxy to a parent hub, under Or paste a token from the hub's admin); or a provider of type: maple in config.yaml
What you needThe hub's sign-in address and your company accountThe hub's model address (ending in /v1) and your token
How long it lasts12 hours at a time, renewed by your proxy for up to 7 days, then you sign in againUntil it expires (30 days for one you made on My access, unless your admin chose another length; never for one an admin made, unless they chose a date) or is revoked
The hub counts requests asYouYou

maple-harness proxy connect --sso does not sign the harness in: it has your local proxy sign in, prints the link and the code, and the harness keeps using your local proxy. No token reaches the harness.

With a pasted personal token, Test the connection says who the hub counts you as ("Connected as <you> at <hub>: your requests count as you"), and Save keeps it without asking. The page leaves Use the hub's people and teams here, and send usage up unticked and greyed out: a personal token uses the hub's models as you, and making the hub this proxy's parent needs a chain token (setup 4). A hub before 2.2.0 cannot say whose a token is: the test then passes with a note saying so.

Connect this proxy to a parent hub after a personal token was pasted: Test the connection says Ready: this proxy joins the hub as you, with The hub answers, The token is accepted, Connected as dana at platform-hub: your requests count as you, The hub is platform-hub, 2 models on the hub; under What to use it for, the parent hub box is unticked and greyed out, with the explanation that this is a personal token.Connect this proxy to a parent hub after a personal token was pasted: Test the connection says Ready: this proxy joins the hub as you, with The hub answers, The token is accepted, Connected as dana at platform-hub: your requests count as you, The hub is platform-hub, 2 models on the hub; under What to use it for, the parent hub box is unticked and greyed out, with the explanation that this is a personal token.
Joining with a personal token: the test says who the hub counts you as. A demo setup.

On the hub, the admin's People & teams shows each person's How they connect lines, with this way first:

How they connect on a hub without single sign-on: first, Their own Maple proxy: paste this token on its Hubs and chaining tab, with the address and the token's place; then Advanced: Maple Harness without a proxy of its own (CI, containers); then Claude Code and OpenCode.How they connect on a hub without single sign-on: first, Their own Maple proxy: paste this token on its Hubs and chaining tab, with the address and the token's place; then Advanced: Maple Harness without a proxy of its own (CI, containers); then Claude Code and OpenCode.
How they connect, without single sign-on. With single sign-on on, signing in comes first (How developers sign in). A demo setup.

What it guarantees.

  • One place for your hub credential: your proxy. The harness never holds a hub sign-in.
  • Everything your proxy sends counts as you at the hub: your budget, your allowed models and accounts. Who on your machine used your proxy is not sent; that is why this is for your own laptop.
  • Your proxy keeps its own accounts, so you can fall back either way: your own account first and the hub when it runs out, or the hub first and a local model when the hub says no (Fallback across the chain).
  • A sign-in renews itself; nothing about your company account is kept on your laptop, only the hub's token for you.

What can go wrong, and how you see it.

What happensHow you see itWhat to do
The hub runs a release before 2.2, or developer sign-in is off there"<host> does not offer sign-in from a proxy …" or "… has sign-in from a proxy turned off …"Ask the hub's admin for a token, or to turn developer sign-in on
Seven days passed since you signed inHubs & chaining and maple-proxy chain status say renewing ended; maple-harness doctor's Proxy line names the hubSign in again, or maple-proxy chain connect --sso again
Your access was revoked at the hub, or you were removed"The hub ended the sign-in", shown at once; maple-proxy chain status says REVOKED: sign in again; a tool's request to the hub gets "The hub … refused this proxy's access (the sign-in was revoked or expired)"Ask the hub's admin; then sign in again
A pasted token expired or was revokedRequests to hub/<model> are refused with "The hub … refused this proxy's token"; the proxy's log has the hub's own answer, and the usage log records not authorised (route reason fallback:not-authorised when a fallback ran)Get a new token and paste it again
The hub cannot be reachedRequests to the hub fail as unreachable, or go to your fallbackCheck the network; set a fallback
Your proxy runs as several replicas, from a ConfigMap, or with read-only secretsThe sign-in is refused and says whyUse a chain token (setup 4)

Step by step: Join your laptop to a team hub, and How developers sign in for the hub's side (My access).

3. A team hub for many people #

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 hub: a token per person, the accounts on one machine.

Pick this if several people should share accounts, and you want to see who used what, give each person or team their own accounts, or cap what each can spend.

What you run. One maple-proxy on a machine your team can reach (a server, a container, or one replica on Kubernetes), listening on the network, with:

  • people and teams, each person with their own token (Teams);
  • optionally single sign-on, so admins sign in to the setup page with their company account and developers make their own tokens and sign their proxies in on My access (How developers sign in).

Each teammate then joins their own proxy to it (setup 2). Tools without a Maple proxy of their own (Claude Code or OpenCode on a machine with no Maple install) use the hub's address with the person's token as their API key.

What it guarantees.

  • Off this machine every request needs a token with the proxy scope, and the proxy will not start on the network until one exists. A request under a host name not in server.allowed_hosts is refused.
  • Every request made with a person's token counts as that person; their budget, model list and accounts apply.
  • The setup page stays on the hub's own machine. Through single sign-on, admins get a second, signed-in address that can do less (no keys, no providers, no machine details).

What can go wrong, and how you see it.

What happensHow you see itWhat to do
No token with the proxy scope exists yetThe proxy does not start on a network address, and says whyMake one on People & teams first
A teammate's tool uses a name the hub does not know403 from the hub's addressAdd the name to server.allowed_hosts
A token is wrong, revoked or expired401, "a valid access token with the proxy scope is required"Make a new token for the person
A budget is spent429, budget_exceededWait for the reset, or raise it
Plain HTTP on a network others shareNothing visible: anyone on that network can read the tokensUse HTTPS, or a private network such as Tailscale or a VPN

The full list of refusals is in When a request is refused.

Step by step: Share Maple with a team, then Set up a team on the People & teams tab, and Single sign-on if you want it.

4. Hubs chained to a company hub #

A company hub at top.example holds the company's accounts, and its people and teams are defined there. A team hub at team.example is joined to it with a chain token: requests go up, people and teams come down, usage goes up. Alice's laptop proxy signed in to the team hub with her company account and is counted as Alice; a CI job uses the team hub directly with a token of its own.A company hub at top.example holds the company's accounts, and its people and teams are defined there. A team hub at team.example is joined to it with a chain token: requests go up, people and teams come down, usage goes up. Alice's laptop proxy signed in to the team hub with her company account and is counted as Alice; a CI job uses the team hub directly with a token of its own.
A company hub, a team hub joined with a chain token, and a laptop signed in to the team hub.

Pick this if there is more than one hub: a hub per team or per office, with people defined once and every hub's usage in one place.

What you run. A proxy per team, each joined to the hub above it with a chain token made by that hub's admin (Hubs & chaining, Let a proxy connect to this hub), pasted on the team proxy (Connect this proxy to a parent hub). Laptops join the team hub as in setup 2.

What it guarantees.

  • People and teams are defined once, at the top, and handed down; a hub below may add its own and tighten an inherited budget or model list, never loosen it.
  • Usage goes up: the top hub reports on every proxy below it, each request counted once. Only counts and labels go up, never prompts, answers or files.
  • Who asked travels up with each request, and only a proxy holding a chain token may say who asked. A chain token belongs to the first proxy that uses it.
  • A revoked token stops working on every proxy below within seconds while the hubs answer.

What can go wrong, and how you see it.

What happensHow you see itWhat to do
The parent hub cannot be reachedRequests without a fallback fail as unreachable; after chain.directory_grace (15 minutes) inherited tokens are refused, the proxy's own keep workingFix the network; usage waits and is sent later, once
A proxy below stopped askingThe hub map marks it not heard lately after five minutesCheck that proxy
The chain token is already used by another proxyTest the connection says it is bound to another proxyUnbind it on the hub, or make a new one
A loop, or more than chain.max_hops proxies (4)Status 508Fix the chain
A child tries to loosen an inherited ruleThe command refuses it, naming the inherited value; the People card offers only TightenAsk the hub above to change it

Step by step: Chain proxies into hubs, and Chained hubs for a worked example with screenshots.

5. Several replicas behind a load balancer #

Clients send requests to one address, a load balancer or a Kubernetes Service, that spreads them over three maple-proxy replicas. Durable data, usage and events, budgets, settings and tokens, and the audit log, is in PostgreSQL. Shared short-lived state, setup-page sessions, rate limits, quota marks and health, caches and conversation pins, is in Redis. The MCP hub, when used, runs as one replica of its own.Clients send requests to one address, a load balancer or a Kubernetes Service, that spreads them over three maple-proxy replicas. Durable data, usage and events, budgets, settings and tokens, and the audit log, is in PostgreSQL. Shared short-lived state, setup-page sessions, rate limits, quota marks and health, caches and conversation pins, is in Redis. The MCP hub, when used, runs as one replica of its own.
Several replicas: PostgreSQL for what lasts, Redis for what is shared and short-lived.

Pick this if a hub (setup 3 or 4) must keep answering through a restart, an upgrade or a lost machine. One replica is enough for most teams: the proxy is light and restarts in seconds.

What you run. Copies of one proxy behind a load balancer, with storage.mode: central, one PostgreSQL and one Redis. Then choose where the settings live:

Settings in PostgreSQL (recommended)Settings from a file (a ConfigMap)
Settingstorage.settings: postgres (the default in central mode)storage.settings: file
Change a settingOn any replica's setup page; every replica runs it within secondsEdit the file and roll the replicas out; read-only on the page
Can replicas drift apart?No: one that cannot confirm it runs the current settings is not readyYes, for a while: Maple reports it, and can take the odd one out
Samplesconfig/ha-shared (Kubernetes), compose.ha-shared.yaml (Docker)config/ha (Kubernetes)
A good fit whenAdmins change settings on the pageEvery change goes through review and Git

No PostgreSQL? Since 2.3, storage.mode: redis keeps everything in one Redis (or Valkey) instead: usage, budgets, settings and tokens. It is supported, but PostgreSQL and Redis together stay the recommendation: in this mode the data lasts only as long as Redis keeps it, so Redis must run with an append-only file and maxmemory-policy noeviction on a persistent disk, with backups (the proxy refuses a Redis that does not), and SQL over the shared usage and the lake need PostgreSQL. Samples: config/ha-redis (Kubernetes), compose.ha-redis.yaml (Docker); details in Kubernetes: without PostgreSQL.

What it guarantees.

  • Any replica serves any request: no sticky sessions, rate limits and budgets counted across replicas, signed-in browsers known to every replica.
  • With settings in PostgreSQL, every replica runs the same configuration, and one that cannot confirm it is current leaves the load balancer (/readyz says not ready) until it is.
  • A replica that stops finishes its running requests first.

What can go wrong, and how you see it.

What happensHow you see itWhat to do
PostgreSQL is away/readyz says not ready; requests of people with a budget get 503 (unless storage.budgets_when_down: open); settings cannot changeBring it back; waiting usage lines are written once
Redis is away/readyz says not ready; the setup page answers 503; caches missBring it back; browsers sign in again
Storage mode redis: Redis stops keeping its data (no append-only file, may evict, or lost its data)/readyz says not ready; Data & storage, Durability, says why; budgeted requests get 503Fix Redis's settings, or restore it from a backup (the messages)
Replicas run different settings (from a file)Data & storage, Settings per replica (in red, below); /healthz adds replicas disagree on configFinish the rollout; see Replicas that disagree
Shared keys differ between replicasThat replica is not ready, and Data & storage says soGive every replica the same storage key
The load balancer adds X-Forwarded-For but is not trustedOne client's wrong tokens get every client refused with 429 for a minuteList the balancer in server.trusted_proxies
The Central storage card on Data and storage for replica-a: mode central; settings from config.yaml (a ConfigMap), read-only on this page; Settings per replica, in red: 2 replicas running, they disagree (2 different settings), each replica's config and access digests and since when, and that a replica whose settings differ from most replicas' is taken out of the load balancer after two minutes; PostgreSQL and Redis reachable; tables up to date; 2 replicas seen; shared keys the same on every running replica.The Central storage card on Data and storage for replica-a: mode central; settings from config.yaml (a ConfigMap), read-only on this page; Settings per replica, in red: 2 replicas running, they disagree (2 different settings), each replica's config and access digests and since when, and that a replica whose settings differ from most replicas' is taken out of the load balancer after two minutes; PostgreSQL and Redis reachable; tables up to date; 2 replicas seen; shared keys the same on every running replica.
Two replicas running different config.yaml files, as when a rollout stopped half way. A demo setup with a local PostgreSQL and a stand-in Redis.

A proxy with replicas cannot keep a company-account sign-in to a hub above it: join it with a chain token.

Step by step: Kubernetes: several replicas and Docker: several replicas.

6. CI jobs and containers #

Pick this if Maple Harness runs in a CI job, a script or a container, where nobody is at a terminal to answer.

In plain words. A run that nobody can answer (--prompt, --rpc, serve, or no terminal) uses the proxy on the same machine only when it can check that the proxy is yours: started as the same user, with the same settings folder. If it cannot check, the run does not start; it exits with status 1 and says how to fix it. It never waits for an answer. So, from the simplest to the most work:

  1. Start the proxy in the job (recommended). Give the job its config.yaml and run maple-harness: it starts its own proxy when nothing answers, or you start maple-proxy serve yourself first, as the same user. The harness checks that proxy on every connection, and you set nothing.
  2. A proxy in a service container (or any proxy the job does not start): connect to it with maple-harness proxy connect and an access token kept in the job's secret store. A container on its own network always needs a token, so this is the way for it.
  3. A proxy on 127.0.0.1 that needs no token but is not yours (run by another user, with another settings folder, or a container on the host's network): set MAPLE_TRUST_UNCHECKED_PROXY=1 for the run, or harness.proxy.trust_unchecked: true in config.yaml.
1. Proxy started in the job2. proxy connect with a token3. MAPLE_TRUST_UNCHECKED_PROXY=1
SettingNoneharness.proxy.url and harness.proxy.token, written by proxy connectThe variable, or harness.proxy.trust_unchecked: true
How the harness knows the proxyIt proves it is yours, on every connectionIts address and its access tokenIt does not: you said to go on
ToolsRun as your rules and --yolo sayRun as your rules and --yolo sayRun as your rules and --yolo say
Access tokenNone neededSent to that address on every requestNever sent: a proxy that needs one refuses the requests
Delegate to your local ClaudeOnOffOff
The harness starts, stops or restarts itYes, when nothing answersNeverNever

GitHub Actions: start the proxy in the job #

The harness starts the proxy from the same settings folder, so it is verified. The provider's key comes from the job's secrets through an environment variable; nothing secret is written in the file.

jobs:
  agent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - name: Install Maple Harness
        run: curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash
      - name: Settings for this job
        run: |
          mkdir -p ~/.config/maple-harness
          cat > ~/.config/maple-harness/config.yaml <<'EOF'
          version: 1
          server:
            openai_compat: 127.0.0.1:11535
            anthropic_compat: 127.0.0.1:11537
            webui: 127.0.0.1:11539
          providers:
            - id: models
              type: openai-compatible
              base_url: https://models.example.com/v1
              api_key: ${env:MODELS_API_KEY}
              models:
                - id: your-model
          model_aliases:
            coder-default: your-model
          EOF
      - name: Run the agent
        env:
          MODELS_API_KEY: ${{ secrets.MODELS_API_KEY }}
        run: maple-harness --yolo --prompt "Fix the failing test" --json-summary summary.json

The same in any other CI, or a plain shell script:

export MODELS_API_KEY=...            # from your CI's secret store
mkdir -p ~/.config/maple-harness     # then write config.yaml as above
maple-harness --yolo --prompt "Fix the failing test"

To see the proxy's log, start it yourself first, as the same user, and wait until it answers:

maple-proxy serve > proxy.log 2>&1 &
for i in $(seq 30); do curl -sf http://127.0.0.1:11535/v1/models > /dev/null && break; sleep 1; done
maple-harness --yolo --prompt "Fix the failing test"

What it guarantees. The harness talks only to the proxy that proves it holds this settings folder's key, so tools run as your rules say. Keep the server: addresses in the file: without them the harness has no proxy address.

GitHub Actions: a proxy in a service container #

A proxy in a container listens beyond its own loopback, so it asks every caller for an access token (see Run the proxy in Docker); no image is published, so use your own build of the Docker sample. Keep the token's value in the job's secrets. The container is given the value, and the harness sends it with mh_ in front:

jobs:
  agent:
    runs-on: ubuntu-latest
    services:
      maple-proxy:
        image: registry.example.com/maple-proxy:2.2.0   # your build of the Docker sample
        ports:
          - 127.0.0.1:11535:11535
        env:
          MAPLE_SECRET_ACCESS_PROXY_TOKENS: ci=${{ secrets.MAPLE_PROXY_TOKEN_VALUE }}
          # its providers and keys: see Run the proxy in Docker
    env:
      MAPLE_PROXY_TOKEN: mh_${{ secrets.MAPLE_PROXY_TOKEN_VALUE }}
    steps:
      - uses: actions/checkout@v5
      - name: Install Maple Harness
        run: curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash
      - name: Connect to the proxy container
        run: maple-harness proxy connect --token-env MAPLE_PROXY_TOKEN http://127.0.0.1:11535
      - name: Run the agent
        run: maple-harness --yolo --prompt "Fix the failing test"

The same in a shell script, with the token in MAPLE_PROXY_TOKEN:

maple-harness proxy connect --token-env MAPLE_PROXY_TOKEN http://127.0.0.1:11535
maple-harness --yolo --prompt "Fix the failing test"

proxy connect checks that the proxy takes the token, then writes harness.proxy.url and harness.proxy.token: ${env:MAPLE_PROXY_TOKEN} into the job's config.yaml; the token itself is never written.

A proxy on 127.0.0.1 with no token, that the harness cannot verify (one run as another user or with another settings folder, or a container with --network host):

MAPLE_TRUST_UNCHECKED_PROXY=1 maple-harness --yolo --prompt "Fix the failing test"

In GitHub Actions, put MAPLE_TRUST_UNCHECKED_PROXY: "1" in the step's env:.

What it guarantees. With proxy connect, the harness trusts the proxy by its address and token, and never starts, stops or restarts it. With MAPLE_TRUST_UNCHECKED_PROXY=1, nothing secret is sent to the proxy: no access token, even one in harness.proxy.token. So a proxy that needs a token is connected with proxy connect, never trusted this way: a run trusted this way that meets one stops at its first refusal and says to connect to it.

When a run does not start #

A run that nobody can answer, on a proxy the harness cannot verify, ends at once with exit status 1 and these lines on standard error (nothing on standard output, and no --rpc events):

You're connecting to an unverified proxy at 127.0.0.1:11535:
it runs as another identity: another user, another settings folder, or a container.
...
This session cannot ask you, so it did not start.

Exit status 1 is also what other errors use; to tell this one apart in a script, look for the line This session cannot ask you, so it did not start.:

maple-harness --prompt "Fix the failing test" 2> harness.err
status=$?
if [ "$status" -ne 0 ] && grep -q "so it did not start" harness.err; then
  echo "the proxy on this machine is not verified: see the CI section of Which setup do I need?" >&2
fi

maple-harness proxy status says the same before a run: its check line names an unverified proxy.

The technical view. "Verified" means the proxy answered a one-time challenge on that very connection with a signature only the holder of the settings folder's local-identity.key can make (see Verified and unverified proxies). The proxy the harness starts, or one you start as the same user with the same XDG_CONFIG_HOME, has that key. A container that does not share the folder, a proxy of another user, or one reached through a port forward does not. A token from harness.proxy.token is sent to a proxy on this machine only after it proved itself, so the 2.1 way of naming a token without harness.proxy.url needs proxy connect now.

There are two ways to reach a proxy you do not start, and they are different things:

Use a proxy or hub directly with a token (advanced)Trust a proxy on the same machine that cannot prove it is yours
WhenA CI job or container that uses a proxy container or a team hub, with no proxy of its ownA proxy run as another user, or with another settings folder, on 127.0.0.1 with no token
Settingharness.proxy.url and harness.proxy.token, written by maple-harness proxy connect <address>harness.proxy.trust_unchecked: true, or MAPLE_TRUST_UNCHECKED_PROXY=1 for one run
What changesThe harness sends every request to that address with the token, and never starts, stops or restarts itTools run as your rules say instead of asking before every run
What stays offDelegate to your local Claude; auth, savings and the quota meter run on the proxy's machineNothing secret is sent to that proxy, and Delegate to your local Claude stays off

For a hub on another machine, the same command takes its address:

maple-harness proxy connect --token-env MAPLE_PROXY_TOKEN https://hub.example:11535

The variable's name must contain TOKEN or KEY (so commands the model runs do not see it). Without --token-env, the command asks for the token without showing it, or reads it from standard input, and keeps it in the secret store. maple-harness proxy disconnect goes back to the proxy on that machine.

What it guarantees. A token is never taken from the command line, and never written into config.yaml as such (only ${secret:...} or ${env:...} references). Plain http:// to another machine is refused unless you pass --allow-insecure.

What can go wrong, and how you see it.

What happensHow you see itWhat to do
An unverified local proxy, and nobody to answer (--prompt, --rpc, serve, no terminal)The harness does not start: exit status 1, and why and how to fix it (below)Start the proxy in the job, connect to it with proxy connect, or set trust_unchecked
trust_unchecked set, and the proxy needs a tokenA run nobody can answer stops after one request: "the proxy at … asks for an access token (401) …", exit status 1; in a session, the same words on the first requestConnect to it with proxy connect --token-env
Your own proxy, updated but not restartedThe same refusal: it is an older release than this harnessmaple-harness proxy restart before the run
Plain http:// to another machine"proxy connect: the proxy at … is reached over plain http …"Use https://, or --allow-insecure on a private network
The variable has another name"… is not named like a secret …"Use a name such as MAPLE_PROXY_TOKEN
The token is refusedproxy connect says so; maple-harness doctor's proxy line tooGet a new token
maple-harness --prompt with no terminal, on a machine whose proxy runs with a different settings folder: You're connecting to an unverified proxy at 127.0.0.1:12535, what that means and where to learn more; then This session cannot ask you, so it did not start; to use it as your own proxy, give it this settings folder; to run with it anyway, harness.proxy.trust_unchecked: true, or MAPLE_TRUST_UNCHECKED_PROXY=1 for one run; or connect to it as a remote proxy, with its access token if it asks for one.maple-harness --prompt with no terminal, on a machine whose proxy runs with a different settings folder: You're connecting to an unverified proxy at 127.0.0.1:12535, what that means and where to learn more; then This session cannot ask you, so it did not start; to use it as your own proxy, give it this settings folder; to run with it anyway, harness.proxy.trust_unchecked: true, or MAPLE_TRUST_UNCHECKED_PROXY=1 for one run; or connect to it as a remote proxy, with its access token if it asks for one.
A run nobody can answer, with an unverified proxy: it does not start, and says what to do. A demo setup.

With trust_unchecked on, maple-harness proxy status says so on its trust line:

MAPLE_TRUST_UNCHECKED_PROXY=1 maple-harness proxy status: the proxy at 127.0.0.1:12535 running, serving 14 models, and the trust line: harness.proxy.trust_unchecked is on: on an unverified proxy here, tools run as your rules say (nothing secret is sent to it and the Claude delegate stays off); its pid, not started by this session, logs off.MAPLE_TRUST_UNCHECKED_PROXY=1 maple-harness proxy status: the proxy at 127.0.0.1:12535 running, serving 14 models, and the trust line: harness.proxy.trust_unchecked is on: on an unverified proxy here, tools run as your rules say (nothing secret is sent to it and the Claude delegate stays off); its pid, not started by this session, logs off.
proxy status while trust_unchecked is on for one run. A demo setup.

Step by step: Connect the harness to a proxy and Verified and unverified proxies.

How to move between setups #

FromToWhat to doWhat is kept
One laptopJoined to a hubSign in (setup 2)Everything: your accounts, settings and usage stay on your proxy
Joined to a hubOne laptopDisconnect on Hubs & chaining, or maple-proxy chain disconnect (the token is revoked at the hub too); for a pasted token, delete the hub's providerYour own accounts and your usage history
Signed in with a company accountA chain token (your proxy now serves others)Paste the chain token on Hubs & chaining: once saved, the sign-in is ended at the hubThe provider name, so hub/<model> keeps working
One laptopA team hubOpen the proxy to the network on a machine the team reaches; add people and tokensIts accounts and usage history; earlier requests stay unattributed
A team hubA team hub under a company hubAsk the company hub's admin for a chain token, paste it, restartYour own people (they become name@your-hub at the top unless defined there)
One proxy (files)Several replicasCopy the settings in with storage.settings_seed or maple-proxy storage import-config --from config.yaml --access access.json; set up PostgreSQL and RedisSettings and access tokens. The usage history in the daily files is not copied into PostgreSQL: keep the files, or load them into a lake
Settings from a ConfigMapSettings in PostgreSQLApply config/ha-shared instead of config/haEverything; the steps
Settings in PostgreSQLSettings from a ConfigMapmaple-proxy storage export-config, then apply config/haEverything; the steps
Harness using a hub directlyHarness using your own proxymaple-harness proxy disconnect, then join your proxy to the hub (setup 2)Your sessions; the stored token can be deleted from the secret store

What is not verified #

The setups on this page were run on one Linux machine: several proxies on loopback with stand-in model services, a stand-in identity provider through a TLS front, and the replicas with a local PostgreSQL and a stand-in Redis. Not yet run: real Google, Microsoft Entra ID, Okta or GitHub accounts, chains over HTTPS between machines, real GitHub Copilot accounts behind a hub, a real Kubernetes cluster, a real Redis, and macOS or Windows. The CI recipes were run as shell commands on Linux, with a stand-in model service and a stand-in for a service container; not on GitHub's own runners.

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