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.

Proxy settings #

On this page
  1. In plain words
  2. Settings at a glance
  3. Listeners and ports
  4. Providers and models
  5. Caching
  6. Images and browser snapshots
  7. Cost visibility
  8. Fallbacks
  9. Guards
  10. Budgets
  11. Alerts
  12. People and teams
  13. Chained proxies
  14. MCP hub (experimental)
  15. Limits and hosts
  16. The usage log
  17. Search by meaning
  18. The setup page, card by card
  19. Single sign-on for the setup page
  20. Observability export
  21. Containers and replicas
  22. Commands
  23. Response headers
  24. Files and environment

This is the complete list of what you can change on the proxy: the cards on its setup page, the keys in config.yaml, the commands, and the response headers you can read. For a guided tour, read The proxy and its setup page first.

The proxy and the harness share one config.yaml. A save on the setup page keeps the harness: section and any setting the proxy does not know, and changes only the lines of the settings you changed, so your comments stay. Adding or removing a provider leaves the other providers as you wrote them; moving a provider up or down the list writes the provider list in the proxy's own layout, without its comments. Saves from the harness, the setup page and maple-proxy commands wait for each other, so none undoes another's change.

Every setting has a Helps column, because each one exists to serve one or more of three goals:

  • Efficient: fewer tokens or AI units for the same work.
  • Efficacious: the work stays as good as it would be without the setting, and the defaults are safe.
  • Effective: whole tasks succeed: the right model answers, and waste is stopped before it grows.

A setting is tagged only where that is true. Where a setting trades one goal against another, the trade-off is stated. Nothing here is a promise about your bill: measure your own tasks.

In plain words #

  • What it is. The complete list of the proxy's settings, cards, commands and response headers.
  • What to do. On the setup page you rarely need this page: each card explains itself, Advanced lists every setting with its default and when it applies, and Find a setting finds one by a word. Come here for the exact key, the default and the trade-off.
Advanced, Every setting: a filter box, then each tab's settings, such as Models & routing's auto mode and guards, each with when it applies, its help, its control, a Docs link and its key.Advanced, Every setting: a filter box, then each tab's settings, such as Models & routing's auto mode and guards, each with when it applies, its help, its control, a Docs link and its key.
The start of Advanced. A demo setup.

Settings at a glance #

On the setup page, the Proxy settings and Auto mode cards are on the Models & routing tab, and Providers is its own tab. Every key in this table is also listed on Advanced, which edits the ones that have no card of their own and says where to change the rest. Find a setting, in the page's menu, finds any of them by name.

KeySetup page cardDefaultHelps
providers[].prompt_cacheProxy settings, CachingautoEfficient
providers[].prompt_cache_keyProxy settings, CachingoffEfficient
providers[].echo_reasoningProviders (config file)offEfficient, Effective
providers[].estimate_costProviders (config file)offEfficacious
providers[].localProviders (config file)worked out from the addressEfficient
providers[].copilot_autoProxy settings, Caching (the Copilot Auto switch on a Copilot provider's row)onEffective
providers[].fusion_review_readsProviders (Let the review read files when editing a Copilot provider)onEffective
providers[].first_output_timeout_secondsProxy settings, Waiting for a slow model30 minutes for a model server you run, 10 for the restEffective
prefix_stabilizerProxy settings, GuardsautoEfficient, Efficacious
context_trim (and its three numbers)Proxy settings, GuardsoffEfficient (a trade-off)
cache_warming (and its two numbers)Proxy settings, CachingoffEfficient (a trade-off)
response_cache (and its two settings)Proxy settings, CachingoffEfficient (a trade-off)
image_resize_tool, image_resize_userProxy settings, GuardsoffEfficient (a trade-off above provider_cap)
image_superseded (and its number)Proxy settings, GuardsoffEfficient (a trade-off)
snapshot_trim (and its number)Proxy settings, GuardsoffEfficient (a trade-off)
model_fallbacksProxy settings, FallbacksnoneEffective
health_failoverProxy settings, FallbacksoffEffective (a trade-off)
model_aliases and model_fallbacks for auto-heavy, auto-medium, auto-lightAuto modederived from the first provider that ranks its modelsEfficient, Effective
auto_avoidAdvanced (shown on Auto mode)["*-codex*"]Effective
auto_first_weightAdvancedheavyEfficient (a trade-off)
context_guardProxy settings, GuardsoffEffective, Efficacious
degenerate_guardProxy settings, GuardsoffEfficient, Effective
budgets[]Proxy settings, BudgetsnoneEfficient, Effective
alerts.*Monitoring, Alert rules (or Advanced)a warning at 80% and 100% of each budget you set; nothing without a budgetEffective
people[], teams[], default_accounts, people_self_viewPeople & teams, PeoplenoneEfficient, Effective
server.rate_limit.*Proxy settings, Limits and hostsoff on this machineEfficacious, Effective
server.allowed_hostsProxy settings, Limits and hostsnoneEfficacious
server.trusted_proxies, server.forwarded_headerAdvancednoneEfficacious
server.usage_ledgerData & storage, Usage data (or Proxy settings, Limits and hosts)on, in the usage folder of your config folderEfficient (it makes spend visible)
server.usage_retention_daysData & storage, Usage data, Keep90 in the default placeEfficient
server.usage_analyticsData & storage, Usage data, Analytics filesoffEfficient (fast questions over long histories)
embeddings.provider, embeddings.modelModels & routing, Search by meaningthe built-in model, once installedEffective
providers[], model_aliasesProvidersdetected for youEffective
server.openai_compat, server.anthropic_compat, server.webuiShown in the page's header; the model addresses' ports on Advancedloopback portsEfficacious
metrics.*, otel.*, log.audit_linesMonitoringoffEffective (monitoring)

Listeners and ports #

KeyDefaultWhat it is for
server.openai_compat127.0.0.1:11535The OpenAI-compatible API (/v1). The harness, and any tool that speaks that API, use it
server.anthropic_compat127.0.0.1:11537The Anthropic-compatible API. Claude Code and similar tools use it
server.webui127.0.0.1:11539The setup page. It refuses to listen on anything but this machine. Leave it empty to turn the page off

Changing an address applies when the proxy restarts. A model API bound to a non-loopback address needs an access token with the proxy scope, made on the setup page; the proxy will not start on such an address until one exists. Efficacious: nothing is reachable beyond your machine unless you say so and create a token.

Providers and models #

A provider is a backend that serves models. The setup page's Providers card builds these for you; this is what the keys mean if you edit the file.

KeyDefaultWhat it does
providers[].idrequiredThe provider's name, for example github-copilot or ollama-main
providers[].typerequiredWhat it is: github-copilot, anthropic, apple-foundation-models, openai-compatible, openrouter, xai, gemini, ollama, lmstudio, omlx, lemonade, unsloth, azure, vertex, bedrock. See Connect a model server, Azure and Google Cloud for azure and vertex, and Amazon Bedrock for bedrock
providers[].base_urlthe type's usual addressWhere the server is
providers[].api_keynoneA key, written as ${env:NAME} or ${secret:name} so it is never a plain value in the file. Keys you type into the setup page go to your system keyring. On the setup page a provider keeps its saved key while its address stays on the same server (the same scheme, host and port, however it is written: the usual port written out or not, upper or lower case); changing the address to a different server saves the provider without the key, so type the key again. An anthropic provider with no key of its own uses ANTHROPIC_API_KEY or the key saved by signing in, and a github-copilot provider uses your Copilot sign-in: the setup page refuses to move one to another server, or to add one at an address other than its own, unless you type that server's key (and, for Anthropic, ANTHROPIC_API_KEY is not set, since it is sent in place of a typed key). Providers written into config.yaml by hand, such as one at a company gateway, keep working as written. If a server redirects a request to another host, port or subdomain, the request is followed without the key; a redirect from https to http is refused. The setup page accepts a key you type or the reference the provider already has. A new ${env:NAME} or ${secret:name} is accepted there only when the page has a password set in a terminal with maple-proxy setup-password set (see More > Protect this page) and you are signed in with it in the browser; otherwise write it into config.yaml by hand. Without a password any program on this computer could open the page, and could also turn a password on from the page itself, so it could point a provider at another of your keys and send that key to a server of its choosing; a password set in a terminal shows that you did it. Maple's own commands, which reach the page without the password, cannot set a new reference either. The variable or secret must exist when you save. A reference to Maple's own credentials (the setup page's, or a stored sign-in) is never accepted. A new reference is the provider's key from that save on, so moving a provider to another server in the same save sends that reference's key there; sending back the reference it already had still counts as the saved key, and is dropped when the server changes
providers[].nicknamenone (the provider's id is shown)What to call this account, for example work or personal; models are shown as work - gpt-5, or github-copilot - gpt-5 without one. It must differ from every other account's name and every provider id, whatever the type. Set by signing in with --as NAME, or by renaming on the setup page or with maple-proxy secrets rename. Display only: it never appears in model_fallbacks or a model's alias, which still name a provider by id
providers[].discount.percentnoneGitHub Copilot only: what you pay off Copilot's list price, in percent (0 or more, under 100), for every request on this sign-in. Shown beside what Copilot charged, never instead of it; budgets and savings are unchanged. See Discounts
providers[].discount.tiersnoneThe same, for requests Copilot Auto or Copilot Fusion routed: auto, fusion (both Copilot Fusion Standard), fusion-high, fusion-max. Wins over percent
providers[].discount.modelsnoneThe same, per model id (claude-opus-5.5: 20), however the model was reached. Wins over tiers and percent
providers[].localworked out from base_urlMarks this provider as running on your own machine or network. The proxy already treats localhost, private and link-local addresses that way; set this for a server reached by a name that does not show it, such as a machine on your network with its own host name. The harness treats a local model as costing nothing, for example when choosing who may summarise a long conversation
providers[].copilot_autoonFor github-copilot only. While your account offers Copilot's own automatic selection, the proxy lists it as the model <provider id>/auto (for example github-copilot/auto): Copilot picks the model for each request. off hides it. It is never listed under the plain name auto, so an alias of that name keeps its meaning. See Copilot Auto
providers[].fusion_review_readsonFor github-copilot only. on lets Copilot Fusion's review (High and Max) read your project's files through your tool's own read-only tools, to check the answer against them, as Copilot CLI's review does; off keeps the review to the task's recorded commands and results. See Copilot Fusion
providers[].first_output_timeout_seconds30 minutes for a model server you run, 10 minutes for the restHow long the proxy waits for this provider to start answering before it gives the request up (and tries a fallback, if you set one). Once the server has answered, a reply may stream for as long as it needs. The longer default applies to the ollama, lmstudio, omlx, lemonade and unsloth types, and to openai-compatible at a local address (see providers[].local): a slow local model, for example one that sends a tool call only once it is complete, can take many minutes to send anything while it works. Raise it for a slow model on a long write; lower it to find a stuck server sooner. Used by the OpenAI-compatible types, maple, azure and vertex; github-copilot, anthropic and apple-foundation-models keep their own. Maple Harness waits at least as long as this (see X-Maple-First-Output-Timeout). When the time runs out the error names the provider and this setting
providers[].workspace_idnoneFor anthropic only: the workspace (wrkspc_...) every request names, needed by a key that is not limited to one workspace. Signing in with such a key asks for it and writes it here; see Sign in. A key limited to one workspace needs none and is safer
providers[].usage_admin_keynoneFor anthropic only: a key used only to read the account's bill from Anthropic, never with a model request. Always ${secret:provider/<id>/usage_admin_key}; set it on the setup page. See Check against Anthropic's bill
providers[].optionalfalseIf the backend cannot be reached at start-up, log a warning and skip it instead of failing to start
providers[].sidecar.command, providers[].sidecar.args, providers[].sidecar.socket_path, providers[].sidecar.dial_timeout_secondsdetectedFor apple-foundation-models only: how the on-device helper is started and reached. You rarely need these. command is a full path, a name on PATH, or a path relative to where the proxy starts; it runs with a minimal environment, and a program or folder any user can change is refused
providers[].azure.api_versionv1For azure only: v1 is Azure's versionless /openai/v1 API; a dated version such as 2024-10-21 uses the older per-deployment route with ?api-version=. See Azure and Google Cloud
providers[].azure.credentialautoFor azure with no api_key: how Microsoft Entra ID is reached: auto (the environment, workload identity, a managed identity, then the Azure CLI), cli, managed-identity, workload-identity or environment
providers[].azure.client_idnoneFor azure with managed-identity (a user-assigned identity) or workload-identity (when AZURE_CLIENT_ID is not set). Not a secret
providers[].azure.tenant_idyour default tenantFor azure with Entra ID: the tenant to ask for tokens in
providers[].azure.anthropic_base_urlthe resource's Foundry addressFor azure: where Claude deployments answer, when not at https://<resource>.services.ai.azure.com/anthropic/v1
providers[].vertex.projectthe credentials' project, or GOOGLE_CLOUD_PROJECTFor vertex only: the Google Cloud project. See Azure and Google Cloud
providers[].vertex.locationglobalFor vertex only: a region (us-east5), a multi-region (us, eu) or global. One location per provider; list several providers for several regions
providers[].bedrock.regionthe AWS configuration's regionFor bedrock only: the AWS region (us-east-1). One region per provider; list several providers for several regions. See Amazon Bedrock
providers[].bedrock.profilethe AWS default chainFor bedrock: the AWS shared-config profile to use, an SSO profile included
providers[].bedrock.role_arnnoneFor bedrock: an IAM role to assume with the credentials found
providers[].bedrock.claude_apiautoFor bedrock: auto sends Claude Opus 4.7 and later through Bedrock's Messages API and older Claude through Converse; messages or converse sends every Claude model that way
providers[].bedrock.access_key_idnoneFor bedrock, only for a fixed AWS key: a ${secret:...} reference to this provider's own secret, written by maple-proxy bedrock store-key. A key itself is refused
providers[].bedrock.secret_access_keynoneThe same, for the key's secret
model_aliasesnoneShort fixed names for models, for tools that want a stable name. A model can also carry its own alias. Editable from the setup page's Model aliases card, or by hand in config.yaml
auto_avoid["*-codex*"]Model-id patterns (case-insensitive) that the proxy's auto mode does not choose by default. [] turns it off. A model you name yourself for a weight is always used
auto_first_weightheavyWhere the proxy's auto starts a new message, before any work is under way: heavy or medium. Planning and questions that ask for judgement stay heavy. See Where a new message starts

Each provider lists its models:

KeyDefaultWhat it does
providers[].models[].idrequiredThe model's id as the backend names it
providers[].models[].aliasnoneA short name, usable anywhere a model is named (/model, fallbacks, budgets)
providers[].models[].context_windowasked from the backendHow many tokens the model can read. Best left out: the proxy asks the backend. Set it only for a server that does not report it
providers[].models[].max_output_tokensbackend defaultThe most one reply may be. State it where the backend's default is small enough to cut a file off mid-line. For a model server you run (the types above, or openai-compatible at a local address) it is also sent when the client asks for no limit, or a larger one, as max_tokens, the name local servers read; and since some servers ignore it, the proxy ends a streamed reply itself once it passes the limit (as a reply cut at its limit: finish_reason length, or stop_reason max_tokens) and stops the server. A cloud provider is sent the client's limit as before
providers[].models[].supports_toolsdetectedWhether the model can call tools. The harness needs this
providers[].models[].categoryfrom the backend, else nonepowerful, versatile or lightweight. Lets /model auto and the proxy's auto mode rank models. Set it (with supports_tools: true) on local models to make automatic choice work there
providers[].models[].effort_levelsfrom the backendThe reasoning-effort levels this model accepts, for example low, medium, high
providers[].models[].min_thinking_budget, providers[].models[].max_thinking_budgetnoneThe bounds of a thinking-token budget, for models that take one
providers[].models[].endpointsfrom the backendWhich APIs the model answers (/chat/completions, /responses, /v1/messages). Set by the sign-in flow
providers[].models[].preview, providers[].models[].chat_default, providers[].models[].billing_multiplierfrom the backendWhat the provider's model list says about a model, where it says it (GitHub Copilot): a preview, the provider's own default, and how it is billed. Auto uses them to choose between models of the same category. Written by sign-in and model refresh; a config without them chooses as before
providers[].models[].auto_modeset for youMarks a model the account can call only inside Copilot's automatic-selection session, which is how the free plan serves its models
providers[].models[].vram_tiernoneA note of the memory a local model needs (for example 8gb); shown, not enforced
providers[].models[].pricenoneThis model's price per million tokens, for a model whose prices are not learned from your requests yet: unit (ai_units or usd), input, cached_input, cache_write (optional) and output. Prices learned from your requests always win. In AI units, the Savings card values the model with it, labelled; in dollars, the cost preview only. Set it on the setup page in the model's ⋯ row. See Prices for each model
providers[].models[].price.unitnoneai_units (GitHub Copilot's AI units: the Savings card values the model with the price) or usd (the cost preview only). Required in a price block
providers[].models[].price.inputnonePrice of a million tokens sent uncached. Required in a price block
providers[].models[].price.cached_inputnonePrice of a million tokens read from the prompt cache; must be below input. Without it, cache reads are not valued
providers[].models[].price.cache_writenonePrice of a million tokens written to the prompt cache; at least input. Leave it out when the provider bills no extra for writes, or reports none
providers[].models[].price.outputnonePrice of a million generated tokens. Required in a price block
providers[].models[].price_asnoneFor estimate_cost on a Claude provider (anthropic, azure, vertex, bedrock): the Claude model ID this model's calls are priced as, such as claude-sonnet-5, when its own name does not say which Claude model it is. Must be a model in Maple's price list, or the configuration is refused when it loads. Set it on the setup page in the model's ⋯ row. See Cost

Helps: Effective, because the right model answering is the largest single factor in whether a task succeeds. Efficient: a lightweight local model costs no AI units at all for the work it can do.

Caching #

Long conversations resend the same beginning on every turn. Providers that cache charge far less for the part they have already seen. These settings help that happen; the Cache card shows whether it did.

KeySetup pageDefaultWhat it doesTrade-offHelps
providers[].prompt_cacheCaching, a switch per providerautoMarks the reusable parts of a request for backends that need telling (Claude through the Anthropic API, or through Copilot). off sends requests unmarkedOff saves nothing and is only for troubleshootingEfficient
providers[].prompt_cache_keyCachingoffSends a stable cache key with each request to an OpenAI-compatible server, so a backend that supports it can route every turn of a conversation to the same cacheA server that does not know the field may reject the request, so it is opt-in per providerEfficient
providers[].echo_reasoningConfig fileoffSends the model's earlier reasoning back to an OpenAI-compatible server that returns it (for example a self-hosted reasoning model), so the model continues from its own thinking during a task instead of re-deriving where it was. Only the task in progress sends itA server that does not know the field may reject the request, so it is opt-in per provider. Measured on one model only (Qwen3.8 on vLLM) and not yet on others, so try it on your own tasks with maple-harness benchEfficient, Effective
prefix_stabilizerGuardsautoKeeps the start of a request identical from turn to turn for tools that do not manage their own caching: it restores a tool list to its first order, and moves a changing line such as the current time to the end of the last messageChanges the position of one line of text in requests from such tools; it never removes or rewrites a tool, and it leaves a request alone when the tool marks its own cache points. off disables itEfficient, Efficacious
context_trimGuardsoffOnce a conversation is long, replaces the content of old, large tool results with a short note, a batch at a timeAnything trimmed is gone from the model's view: it may ask for it again, which costs a request. Best for long runs with large tool output; leave off for short sessionsEfficient
context_trim_after_tokensGuards60000The estimated conversation size at which trimming beginsA lower value trims sooner and rewrites the cached start more oftenEfficient
context_trim_keep_recent_turnsGuards6How many of the latest turns are never trimmedA higher value keeps more context and saves lessEfficacious
context_trim_min_result_tokensGuards1000The smallest tool result worth replacingA lower value trims more, smaller resultsEfficient
cache_warmingCachingoffWhile a conversation sits idle, sends a small refresh so the provider's cache does not expire before your next message arrives — so that message still gets the cheaper, cached price instead of paying to rewrite the cache from scratch. Only for providers where the proxy knows the vendor's own cache lifetime; today that is Anthropic's built-in cacheIt spends a little to try to save more later, and does not always pay off — if you were about to send your next message anyway, the refresh bought nothing. For each model it starts only after the proxy has seen enough of your own requests to that model to estimate what a cached and an uncached token cost, and only when the expected saving is at least cache_warming_min_savings_ai_units. off by defaultEfficient (a trade-off)
cache_warming_min_savings_ai_unitsCaching0.05The smallest expected saving worth sending a refresh forLower sends more refreshes, some of which will not pay offEfficient
cache_warming_continuation_probabilityCaching0.15How often you send your next message before the cache would have expired anyway, so a refresh turns out to have been unnecessary. A starting estimate, not measured on your own traffic yetHigher makes the feature more cautious about sending refreshes at allEfficient
response_cacheCachingoffon returns the saved answer to an identical, repeatable request within response_cache_ttl, without asking the provider again. Repeatable means the client sends the request header X-Maple-Cache: allow, or a temperature of 0 that reaches the provider; the proxy does not pass a temperature of 0 on to providers today, so in practice only the header qualifies. Never a request with images, or whose last message is a tool call or a tool result, and only an answer that finished normally (not cut short, not a tool call, not an error) is saved. An answer is only ever returned to the same client (the same access token, or the same kind of tool on this machine) and the same provider account that asked for it. Answers are kept in memory only, never on disk, and are dropped when these settings change or the proxy stops. The response says what happened in X-Maple-Cache-ResponseA reused answer is the same text as before, not a fresh one: turn it on only for clients that send the same request again and want the same answer. To see how often it would have answered on your own traffic before turning it on, run maple-proxy usage cache-potentialEfficient (a trade-off)
response_cache_ttlCaching5mHow long a saved answer is kept, as a duration from 1s to 24hLonger answers more repeats, with answers that may be olderEfficient
response_cache_max_mbCaching64The most memory saved answers may take, in MB (up to 4096). One client may use at most a quarter of it, and makes room by dropping its own least recently used answers, never another client'sMore keeps more answers, in the proxy's memoryEfficient

Images and browser snapshots #

A model is charged for an image by its size in pixels, not by its file size, and a large image is scaled down by the provider before the model looks at it. Browser tools also return page snapshots (a text outline of the page) that are often the largest thing an agent resends. These settings shrink both. All of them are off by default.

KeySetup pageDefaultWhat it doesTrade-offHelps
image_resize_toolGuards, Images from toolsoffShrinks images a tool produced, such as a browser screenshot, before they are sent. provider_cap never sends more pixels than the model's provider says it uses; balanced scales large images down to about 1280 by 800 pixels' worth; aggressive to about 1024 by 640provider_cap costs the same tokens (the provider would have scaled the image down itself) and only saves upload size; it acts only for models whose provider publishes its rule (Claude, and OpenAI's tile-priced models such as gpt-4o and gpt-4.1), and only when the smaller file really is smaller. balanced and aggressive save tokens, and small text in a screenshot may become harder to read. They always send fewer pixels, but an image PNG had already squeezed very small (a repeating pattern, a screenshot with large flat areas) can come out larger in bytes; the report below shows the sizesEfficient (a trade-off above provider_cap)
image_resize_userGuards, Images you attachoffThe same levels, for images you attach yourselfAs aboveEfficient (a trade-off above provider_cap)
image_supersededGuards, Replace older tool imagesoffOnce a newer image from the same tool follows, replaces the older one with a one-line note. Images you attach are never replacedThe model can no longer see the older image. Each replacement changes an earlier message, so the provider re-reads what follows it once: with a provider that caches prompts this can cost more than it saves, and the Savings card counts those rewrites as a costEfficient (a trade-off)
image_superseded_after_turnsGuards, Also after (turns)noneAlso replaces a tool image once this many of your turns have passed since it arrivedAs aboveEfficient
snapshot_trimGuards, Trim browser snapshotsoffFor page snapshots from a browser tool (Playwright MCP): leaves out empty layout nodes, separators and images without a text alternative, folds runs of identical items into one line that still lists each item's reference, and, when the page did not change address since the last snapshot, sends only what changed since the last full snapshot of that page, with the nodes around each change. A new address, or a change too large for a list of changes to help, sends the full snapshotThe model reads changes against an earlier snapshot instead of a fresh full page. A result is only treated as a snapshot when it clearly is one; anything else is left exactly as it came. Recent Playwright MCP versions include the snapshot only in browser_snapshot results (after a click they link to a file, which is left alone), and a page that rebuilds its elements gets new references for all of them, so its next snapshot goes in fullEfficient (a trade-off)
snapshot_trim_max_tokensGuards, Largest snapshot (tokens)12000A snapshot larger than this is cut, with a note saying how many lines were left outThe model does not see the end of a very large page until it asks for a smaller part of itEfficient

When images are resized or replaced, the response carries X-Maple-Images with the count, the estimated tokens saved and the measured sizes before and after; the harness shows it as a note on screen (it is not sent to the model), and the proxy log has a line for each request with images, including the ones left untouched.

Everything here gives the same result for the same conversation, so a conversation resent on every turn keeps using the provider's cache. An image that cannot be read, is rotated by its camera data, or is animated is sent as it came, and no image is ever made larger. The Savings card shows what each of these left out on its own line, as an estimate, and does not add it to the headline figure.

Cost visibility #

Copilot states what a call cost, in AI units, on every response. Anthropic's own API never does — it reports token counts only. /cost (see What /cost tells you) still shows a per-request figure for Anthropic when this is on, but it is a guess from Anthropic's published prices, not a bill, and is always shown labelled as one — real dollars, never added to the AI-units figure Copilot's calls carry.

KeySetup pageDefaultWhat it doesTrade-offHelps
providers[].estimate_costConfig fileoffFor a type: anthropic provider, prices each call from Anthropic's own published per-model rates, when Anthropic itself reported no price (it always does)The price list is read once, from this repository, not fetched live — if Anthropic's prices change, an old build's estimate is wrong until it is updated. Off by default: an estimate could be mistaken for what you were actually billedEfficacious

Fallbacks #

KeySetup pageDefaultWhat it doesTrade-offHelps
model_fallbacksFallbacksnoneFor a model or alias, the names to try in order when it cannot answer: its account is out of chats or credit, the backend is overloaded, or it is unreachableA fallback may be a weaker or a different model, so results can differ. It happens only before any output is sent, and never for bad credentials or malformed requests. A fallback's own fallbacks are not followedEffective
provider_fallbacksFallbacksnoneFor a provider (one signed-in account), where its requests go when it cannot answer: another provider id, which asks it for the same model, or <provider id>/<model>, which asks it for that model. Tried after the model's own model_fallbacks. Also used when the account itself is refused (signed out, or a seat removed)The same trade-offs as model_fallbacks. Only the chain of the provider serving the model you asked for is followed, not the chain of a fallback's provider. A provider id step is skipped when that provider does not serve the model. A later step may be a cloud provider, so a request a local provider cannot take goes thereEffective

For example, two Copilot accounts, then Anthropic, then a local model:

provider_fallbacks:
  github-copilot:           [github-copilot-personal, anthropic/claude-sonnet-5, local/qwen3-coder]
  github-copilot-personal:  [anthropic/claude-sonnet-5, local/qwen3-coder]

When two accounts serve a model with the same name, a plain name goes to the last of them in the config (as in earlier versions; the proxy log says which), and <provider id>/<model> reaches a particular account's copy. This form works anywhere a model name does, including in model_fallbacks and as the model in a request, and the model list shows the other account's copy under it.

Responses from a fallback say so in X-Maple-Fallback-From and name the model that answered in X-Maple-Served-By. A fallback whose known context window is too small for the request is passed over (the header says so), one whose window is unknown is still tried, and when nothing on the list fits, the request is refused with an error that says so.

A model that has just answered that its account is out of quota is tried last for the next hour, so requests go straight to its fallbacks instead of waiting for the same refusal each time; X-Maple-Fallback-From names it with quota exhausted. It is not dropped: when everything else fails, or it has no fallbacks, it is still asked, and as soon as it answers again it goes back to its usual place. Without provider_fallbacks, that is the only thing the proxy remembers about a failure.

KeySetup pageDefaultWhat it doesTrade-offHelps
health_failoverFallbacks, the Health failover switchoffThe proxy always watches how each model answers on your own traffic (see Provider health); with off it only watches, and a response from a model it would demote says so in X-Maple-Router. on tries a demoted model after the other fallbacks you configured for that request, ahead of any known to be out of quota. It never adds a model or a provider, and never drops one: with nowhere else to go, the demoted model is still asked. A demoted model gets a real request again after a hold, and goes back to its place when it answersRequests can move to a fallback that is slower, weaker or priced differently, so what you spend can change; route_reason in the usage log says health-demoted for each oneEffective

For a provider that is part of a provider_fallbacks chain (the provider a chain starts from, or a step in one), the proxy remembers a little more, always in the same "tried last, never dropped" way:

  • Out of quota or credit: for as long as the provider's Retry-After says (at most a day), or an hour. Usually only that model is moved, because a Copilot account out of premium requests still answers with its included models; when the answer says the whole account has no credit or a billing problem, every model on it is moved.
  • Rate limited: for as long as Retry-After says, at most an hour, and only that model. A rate limit without Retry-After is not remembered.
  • Refused: for an hour. Every model on the account is moved only when the sign-in itself failed (bad or expired credentials, a revoked token, a suspended account). Any other refusal, such as a model your organisation's policy does not allow, moves only that model.
  • A Copilot account whose monthly chats are used up is moved before any request is spent on it, until the reset Copilot gives or for an hour, whichever is sooner; then it is asked again in its usual place, which also reads its meter afresh.

Guards #

KeySetup pageDefaultWhat it doesTrade-offHelps
context_guardGuards, a three-way choiceoffFor tools that do not know a model's window: off sends the request as it is, truncate drops the oldest whole turns until it fits, error refuses it with a plain messagetruncate silently forgets old turns; error stops the requestEffective, Efficacious
degenerate_guardGuards, the repeat guard switchoffCuts off a streamed reply that has collapsed into repeating itselfA legitimately repetitive answer could be cut shortEfficient, Effective

Budgets #

KeySetup pageDefaultWhat it doesTrade-offHelps
budgets[].providerBudgetsnoneWhich provider the limit applies toEfficient
budgets[].max_requests_per_dayBudgetsnone (no limit)The most requests a day for that provider (days are UTC)When reached, requests are refused, or handed to that provider's fallbackEfficient, Effective
budgets[].max_ai_units_per_dayBudgetsnone (no limit)The most AI units a day for that providerAs above; counts come from the usage log, so they survive a restart while the log is on (the default)Efficient, Effective
budgets[].max_usd_per_monthCosts & budgets, Monthly dollar budgetsnone (no limit)A monthly allowance in estimated dollars at the provider's list prices, through this proxy only. See Monthly dollar budgetsAn estimate: the provider's console is the authorityEfficient, Effective
budgets[].month_starts_on_dayCosts & budgets, Monthly dollar budgets1The day the dollar month resets, at 00:00 UTC (a day past the month's end means its last day)Effective
budgets[].when_spentCosts & budgets, Monthly dollar budgetsfallbackAt 100% of the dollar budget: warn, fallback (refuse this account, so fallbacks are tried) or stop (refuse the request)warn lets spend go past the amountEfficient, Effective
budgets[].sourceCosts & budgets, Monthly dollar budgetsnoneA label: subscriber_credits, purchased or spend_limit. Wording only

Alerts #

Alerts only warn: they never refuse, reroute or slow a request (budgets do the refusing). Each alert fires once per rule and period, is written to the events log, and is sent to clients in X-Maple-Alert while it is in force; Maple Harness shows it once. With no budget and nothing set here, there are no alerts. See Alerts and forecasts.

KeySetup pageDefaultWhat it doesTrade-offHelps
alerts.budget_fractionsAlerts[0.8, 1] for each budget you setThe shares of each budget (budgets[]) at which to warn, once per budget per UTC day each. [] turns budget alerts offMore levels, more messagesEffective
alerts.quota_fractionsAlertsnone (off)The shares of a provider's own quota (as the provider reports it, such as a monthly allowance) at which to warn, once per quota per reset period. The proxy asks the provider once a minute while this is setA provider that does not report its quota gives nothing to warn aboutEffective
alerts.daily_spend_ai_unitsAlertsnone (off)Warn once a UTC day when that day's AI units, across every provider, pass thisEffective
alerts.daily_spend_costAlertsnone (off)The same for the estimated list-price cost (USD), for providers set up to give oneAn estimate, not a billEffective
alerts.error_rateAlertsnone (off)Warn when more than this share (0.25 is 25%) of the last hour's requests failed. Requests a client cancelled and requests a budget refused do not countEffective
alerts.error_rate_min_requestsAlerts20How many requests the last hour must hold before error_rate is judgedLower reacts sooner and to fewer requestsEffective
alerts.headerAlertsnone: each caller gets only their own alertsWho gets X-Maple-Alert. Unset: a tool on the proxy's own machine without a token gets every alert, a person (a token tied to someone in people:) only the alerts about their own budget, and any other token none. all sends every alert to every caller, for one owner who reaches their own proxy from another machineall on a proxy other people use tells them about your providers and spendEffective
alerts.webhooks[]Alerts, Webhooksnone (off)Where each alert is sent as it fires (text, level, rule, id and time only). See AlertsThe address leaves your machine with each alertEffective
alerts.webhooks[].idAlerts, WebhooksrequiredA name: letters, digits, - and _Effective
alerts.webhooks[].urlAlerts, WebhooksrequiredA reference to the https address: ${secret:alerts/webhook/<id>/url} (what the page and CLI write) or ${env:MAPLE_WEBHOOK_...}. The address itself is refused here: anyone holding it can post to your channelEffective
alerts.webhooks[].formatAlerts, Webhooksjsonslack, teams (an Adaptive Card for a Teams workflow) or jsonEffective
alerts.webhooks[].secret_refAlerts, Webhooksnone (unsigned)${secret:alerts/webhook/<id>/signing} or ${env:MAPLE_WEBHOOK_...}: sign each request (the request headers X-Maple-Timestamp and X-Maple-Signature)A webhook whose secret cannot be found is not sent toEffective
alerts.webhooks[].audienceAlerts, Webhooksadmin (every alert)person:<id>: only that person's own budget alertsEffective
alerts.webhooks[].allow_privateAlerts, WebhooksfalseAllow an address on this machine or a private network. Link-local and cloud-metadata addresses are always refusedEffective
alerts.webhooks[].allow_http_loopbackAlerts, WebhooksfalseAllow plain http to this machine (needs allow_private)Effective

People and teams #

All optional, and off until set: without them every request is served as before. See Teams.

KeySetup pageDefaultWhat it doesTrade-offHelps
people[].idPeoplenoneA person, as the usage log's person column names them. local is a caller on this machine without a tokenEfficacious
people[].teamPeoplenoneThe person's team: the team column, and the team's budget, models and accountsEfficacious
people[].tokensPeople, tie a tokennoneThe ids of the person's access tokens (never the tokens). A token belongs to one personA proxy token tied to nobody is unattributed and has no person's limitsEfficacious
people[].budget.daily_ai_unitsPeople, budgetnone (no limit)The most AI units a UTC day for the personRefused with budget_exceeded once spent; running requests finishEfficient, Effective
people[].budget.monthly_ai_unitsPeople, budgetnone (no limit)The most AI units a UTC monthAs aboveEfficient, Effective
people[].budget.daily_usd, people[].budget.monthly_usdPeople & teams, Edit, Dollar capnone (no limit)The most estimated dollars a UTC day, and a UTC calendar month, for the person (Monthly dollar budgets)As above; an estimate at list pricesEfficient, Effective
people[].models.allowPeople, modelsevery modelThe models the person may use: names, ids or account/model, with *Others are refused with model_not_allowedEfficient, Effective
people[].models.fallbacksConfig filenoneReplaces model_fallbacks for the person, per model asked forEffective
people[].accountsPeople, accountsnoneProvider accounts (ids or nicknames) tried first, in orderEffective
people[].accounts_onlyPeople, accountsoffLimits the person to their own and their team's accountsAnything else is refusedEfficient
people[].sign_in_markerNever shownwritten by the proxyTies the person's single sign-on (the accounts they sign in with, their terminals, the tokens they made for themselves) to them, so someone added later with the same id is not signed in by the old account. Leave it as it isRemoved or changed by hand (or by going back to 2.1.x, which drops it), the person signs in againEfficacious
teams[].idPeople, teamsnoneA team with settings of its own; a team named only by its people needs no entryEfficacious
teams[].budget.daily_ai_unitsPeople, team budgetnone (no limit)The most AI units a UTC day for the whole teamA refusal names the team, not its figuresEfficient, Effective
teams[].budget.monthly_ai_unitsPeople, team budgetnone (no limit)The most AI units a UTC month for the whole teamAs aboveEfficient, Effective
teams[].budget.daily_usd, teams[].budget.monthly_usdPeople & teams, Teams, Edit, Dollar capnone (no limit)The most estimated dollars a UTC day, and a UTC calendar month, for the whole teamAs aboveEfficient, Effective
teams[].models.allowPeople, team modelsevery modelThe models the team's people may use when they have no list of their ownEfficient, Effective
teams[].models.fallbacksConfig filenoneFallbacks for the team's people, when they have none of their ownEffective
teams[].accountsPeople, team accountsnoneAccounts tried after the person's ownEffective
teams[].accounts_onlyPeople, team accountsoffLimits the team's people to their accountsEfficient
default_accountsPeoplenoneAccounts tried first for everyone, after a person's and a team'sEffective
people_self_viewPeople, the self view switchoffTurns on GET /v1/maple/me/usage: each person's own figures, with their own tokenEfficacious
setup_page.sso.*Single sign-on, the wizard (this machine's page only)offSingle sign-on to the setup page for team admins and, if you turn it on, developers (Google, Microsoft Entra ID, Okta, GitHub, any OpenID Connect provider), on an address of its own. See Single sign-on for the setup page and How developers sign inAdmins there cannot change providers, keys, settings, single sign-on or remote control; developers see My access onlyEffective

Chained proxies #

All optional: a proxy takes part in a chain only once it has a provider of type maple or a proxy-chain token. See Chain proxies into hubs.

KeySetup pageDefaultWhat it doesTrade-offHelps
providers[].type: mapleProvidersnoneAnother Maple proxy used as a provider (a hub). base_url is its OpenAI-compatible address, api_key a token from maple-proxy chain token there. Any of its models is reached as <id>/<model>base_url must be https:// unless the hub is on this machine or your local network, or local: trueEffective
server.proxy_nameChained proxiesnone (the generated id)A readable name for this proxy in usage records, its own and other proxies'Efficacious
chain.max_hopsChained proxies4The most proxies a request may have passed through before this one (1 to 16); more, or a request coming back to a proxy it passed, is refused with 508. Read at startEffective
chain.parentChained proxiesnoneThe maple provider whose hub this proxy inherits people and teams from and sends its usage records toEfficacious, Effective
chain.directory_intervalChained proxies60sHow often the parent is contacted (10s to 168h)Efficacious
chain.directory_graceChained proxies15mHow long the inherited people are trusted while the parent cannot be reached; after it, inherited tokens are refusedShorter is stricter about revoked tokens; longer rides out a hub restartEffective
chain.report_usageChained proxieson with a parentoff stops sending usage records upThe hub then counts this proxy's requests only as linesEfficacious

MCP hub (experimental) #

Off until mcp_hub.enabled is set; while off nothing listens and nothing starts. See MCP hub.

KeySetup pageDefaultWhat it doesTrade-offHelps
mcp_hub.enabledMCP hub, the switchoffServes the configured MCP servers' tools at one MCP endpointA bridge from that endpoint to programs on this machineEfficient
mcp_hub.listenConfig file127.0.0.1:11545Where the endpoint is served (path /mcp). Every request needs an mcp-hub token, on this machine too unless loopback_without_tokenEfficacious
mcp_hub.loopback_without_tokenConfig fileoffLets callers on this machine use the hub without a tokenAnything running on this machine, a sandboxed command included, could call every toolEfficient
mcp_hub.tls_certConfig filenoneCertificate (PEM) for serving off this machine; with tls_keyEfficacious
mcp_hub.tls_keyConfig filenoneIts key (PEM)Efficacious
mcp_hub.insecure_httpConfig fileoffServes off this machine over plain HTTPTokens cross the network unencryptedEfficacious
mcp_hub.sandboxConfig fileautoHow a program the hub starts is contained: auto, strict or offoff runs it with your full permissionsEfficacious
mcp_hub.allow_uncontained_stdioConfig fileoffIn the container image only: lets stdio servers start without a sandbox. Without it a stdio server there starts only inside a working sandbox, and the image has none, so it is refused; run the server as its own container and add it by URL instead (see Kubernetes)The program can read everything the hub's container can, its mounted secrets included, and reach the networkEfficacious
mcp_hub.rate_limit_per_minuteConfig file120Tool calls a minute per tokenEfficient
mcp_hub.peopleConfig filenonePer-person lists of hub tools (server__tool, with *); local, unattributed and * tooWith lists, someone unlisted gets no toolsEfficacious
mcp_hub.servers[].nameMCP hub (shown)requiredThe server's name, the first part of its tools' names: letters, digits and dashesEfficacious
mcp_hub.servers[].typeConfig filestdio for a command, http for a urlstdio, http or sseEfficacious
mcp_hub.servers[].commandConfig file, or maple-proxy mcp-hub addnoneThe program to start for a stdio serverAdded only in a terminal or the file, never the setup pageEfficacious
mcp_hub.servers[].argsConfig filenoneIts argumentsEfficacious
mcp_hub.servers[].envConfig filenoneKEY=VALUE pairs for it; a value may be ${secret:name}Efficacious
mcp_hub.servers[].urlConfig filenoneA remote server's addressEfficacious
mcp_hub.servers[].headersConfig filenoneHeaders sent to it; a value may be ${secret:name}Efficacious
mcp_hub.servers[].allow_privateConfig fileoffAllows a remote server on this machine or a private networkEfficacious
mcp_hub.servers[].allow_insecureConfig fileoffAllows plain http to another machineIts headers cross the network unencryptedEfficacious
mcp_hub.servers[].toolsConfig fileevery toolOnly these of the server's tools; * matches any run of charactersEfficient
mcp_hub.servers[].disabledMCP hub, the server's switchoffKeeps the server configured but not startedEfficient

Limits and hosts #

These are read when the proxy starts. After changing them, stop and start maple-proxy.

KeySetup pageDefaultWhat it doesHelps
server.rate_limit.enabledLimits and hostsunset: off for this machine, on for other addressesForce the limit on or offEfficacious
server.rate_limit.requests_per_minuteLimits and hosts60The sustained rate per clientEfficacious
server.rate_limit.burstLimits and hosts20How many requests may arrive at onceEfficacious
server.rate_limit.perLimits and hoststokenCount clients by access token (else by address) or by ipEfficacious
server.rate_limit.max_concurrentLimits and hosts8Requests in flight per client, so one client cannot hold every stream openEfficacious, Effective
server.allowed_hostsLimits and hostsnoneExtra host names the proxy answers to, one per line, for example a Tailscale name. Names only, no https:// and no pathEfficacious
server.trusted_proxiesConfig file (MAPLE_TRUSTED_PROXIES adds to it)noneThe load balancers or ingresses in front of the proxy, as addresses or CIDRs (10.0.0.0/8). A request from one of them counts as coming from the client its forwarding header names, for the wrong-token limit, a per-address rate limit and the audit log, so one client's wrong tokens refuse that client and not everyone behind the balancer. (A valid token is never refused by this limit, from any address.) A header from any other address is ignored. List only the balancers' own addresses: anything inside a listed range can name its own client address. Wider than /8 (IPv4) or /16 (IPv6) is refusedEfficacious
server.forwarded_headerConfig filex-forwarded-forThe header those balancers set: x-forwarded-for or forwarded. Only that one is readEfficacious

A client over its limit receives a 429 with a Retry-After header in the shape of the API it called.

The usage log #

KeySetup pageDefaultWhat it doesHelps
server.usage_ledgerUsage data, Location (or Limits and hosts, Usage log)on: usage/maple_harness_proxy_usage_ledger.jsonl in your Maple Harness config folderWhere the usage log goes: a file that receives one line of numbers per request (model, tokens, cache figures, AI units, timing), one file per UTC day. Budget counts come from it (the Cache, Sessions and Savings cards survive a restart on their own, without it). It holds counts and labels only, never prompts or answers. Leave it unset (or empty) for the default place, give a full path (or one starting with ~/) to put it elsewhere, or set it to off to turn it off. The Usage data card's Move, Use the default place, Turn off and Turn on buttons set it for you and apply at once, without a restart, unless CCH_USAGE_LEDGER is set; a path that cannot be written is refused with the reason. An empty value, which earlier releases saved while the log was off, now means the default place too, so the log is on after upgrading; only off turns it offEfficient (it makes spend visible)
server.usage_ledger_notice_seenUsage data, the notice's OK or Turn offnot setSet when you answer the one-time notice that the usage log is now on by default, so the setup page (on any browser) and maple-proxy usage status stop showing it. The notice appears only while the log is on because of the default, not when you set a pathEfficient
server.usage_retention_daysData & storage, Usage data, Keep90 in the default place; unset elsewhereHow many days of daily usage files to keep. Older daily files are deleted when the proxy starts and once a day; 0 keeps everything. Unset, it is 90 days in the default place (only files named maple_harness_proxy_usage_ledger-YYYY-MM-DD.jsonl, in the folder the proxy created) and nothing is deleted for a path you chose, until you set it. Only the log's own daily files are deleted: never the undated file from releases before daily files, never a file that is not a usage log file, never anything else in the folder, and never a link or a hard-linked file. A folder you chose that is itself a link is followed, as the log follows it. Each cleanup that deletes files is recorded in the audit log (how many, and the folder). Saved from the card, it applies without a restartEfficient (bounds the disk the log uses)
server.usage_analyticsData & storage, Usage data, Analytics filesoffCopies of the usage log made for fast questions over long histories, in an analytics folder inside the log's folder, refreshed once a day after the cleanup: parquet packs each month's closed days into one Parquet file per month; duckdb also keeps a maple_usage.duckdb file; lake also keeps a DuckLake. duckdb and lake run your own duckdb command line when it is installed (nothing is downloaded). A monthly file goes as soon as a day it was made from is deleted. off makes nothing; files already made stay until you delete them. Applies from the next daily run, without a restart. See Lots of history?Efficient

The Usage data card shows how much disk the daily files take, how many there are and which days they cover, and, once there is a whole day of data, an estimate of their size when the full retention is kept. As an estimate: a request with no cost or savings figures takes about 0.25 KB in the log and a priced one about 0.65 KB (measured on sample lines), so 1,000 requests a day for 90 days is roughly 22 to 58 MB. maple-proxy usage status prints the same in a terminal. CCH_USAGE_LEDGER in the proxy's environment overrides the setting: a path, or off.

Search by meaning #

Which model ranks the harness's searches by meaning. See Search by meaning for what it does, both models, their licences (EmbeddingGemma is under the Gemma Terms of Use and the Gemma Prohibited Use Policy, and its download needs a Hugging Face token from an account that accepted them) and hardware guidance: EmbeddingGemma built in is comfortable with more than 8 GB of memory and 4 or more CPU cores.

KeySetup pageDefaultWhat it doesHelps
embeddings.engineSearch by meaning, the engine switchbuilt in, unless base_url or provider is setbuiltin (a model that runs inside the proxy) or server (your own OpenAI-compatible embeddings server). With builtin, the server settings below are kept for switching back. Applies without a restartEffective
embeddings.builtin_modelSearch by meaning, Use this modelbge-small-en-v1.5Which built-in model answers: bge-small-en-v1.5 or embeddinggemma-300m. It must be installedEffective
embeddings.base_urlSearch by meaning, Your own server, Base URLnoneYour embeddings server's OpenAI-compatible address, for example http://127.0.0.1:11434/v1 for Ollama. An address that is not on this machine or your own network is refused. No user name, password or query in itEffective
embeddings.modelSearch by meaning, Your own server, ModelnoneThe model's name at that server or provider, for example embeddinggemma. Required when embeddings.base_url or embeddings.provider is setEffective
embeddings.api_keySearch by meaning, Your own server, API keynoneSent to that server as a bearer token. The setup page keeps it in the secret store and writes ${secret:embeddings/api_key} here. Written into the file by hand, ${env:EMBEDDINGS_NAME} (a variable whose name starts with EMBEDDINGS_) works too; no other reference is used for this key. Never shown back, and cleared when the server's address changesEffective
embeddings.localSearch by meaning, This address is on my own networkfalseVouches that base_url is on your own network when its name alone does not show it. Set it only for an address you controlEffective
embeddings.providerSearch by meaning, Your own server, Or usenoneInstead of base_url: the id of a local OpenAI-compatible provider from the Providers card whose /v1/embeddings answers. Its own key is used. A provider that is not on this machine or your own network is refusedEffective
embeddings.cacheSearch by meaning, Cache, Keep computed vectorsonon or off. Keeps each vector the model computes, so the same text is not computed again by the same model. A different model, revision, vector length or side of a search (query or document) never shares an entry. Applies without a restartEffective
embeddings.cache_diskSearch by meaning, Cache, Also on diskonon or off. Also keeps the vectors on disk, in the config folder's embeddings/cache/, so they survive a restart. The files hold the vectors and a hash keyed with a secret made for your install, never the text. With off, the cache is in memory only and existing files stay until clearedEffective
embeddings.cache_max_mbSearch by meaning, Cache, Largest size on disk256The most the cache keeps on disk, in MB; the oldest entries go first when it is full. Memory holds up to 64 MB of it, or this much if smallerEffective

The proxy serves POST /v1/embeddings (the OpenAI request and response shape, up to 64 texts per request) and GET /v1/embeddings/info (which model answers, or why none does) on its OpenAI-compatible address, with the same protection as the rest of that address. With nothing installed or chosen, /v1/embeddings answers 503 with the reason. It works on one request at a time with at most four waiting; past that it answers 429 with Retry-After: 2. When it forwards to your server it follows no redirect and ignores HTTP_PROXY and HTTPS_PROXY, and an error from the server is reported in plain words with what to do, without the server's address, its key or its response text.

The Hugging Face token for a gated built-in model is not a config key: save it on the card (it goes to the secret store) or set HF_TOKEN in the proxy's environment, which is used first.

The setup page, card by card #

CardWhat it shows and does
Account (Providers tab)Sign in to GitHub Copilot (a browser flow) or save an Anthropic API key. The Copilot plan and, where the plan has one, the chats left and when they reset
Providers (Providers tab)The configured backends and their models. Add a server, press Detect models, edit or delete
Remote access (Security & access)The master switch for remote control, access tokens for devices (short pairing codes, links, or fixed tokens), what each token may do, the folders a phone may start sessions in, and the gateway's addresses. A new token first asks what it is for: A phone or browser to follow and drive sessions (remote control) or A person's tools to send model requests (the proxy scope only; for a person on a team, Make a token on People & teams ties it to them at once)
Auto mode (Models & routing)What auto, auto-heavy, auto-medium and auto-light resolve to. For each weight, a model (any configured model, or Copilot Auto) or Use defaults, an optional list of fallbacks, and a preview of where a request goes. Saves model_aliases and model_fallbacks entries; see Auto mode at the proxy
Proxy settings (Models & routing)Caching, Fallbacks, Guards, Budgets, and Limits and hosts: every setting above as forms and switches, with a Review changes diff before saving and a What this will do summary
Cache (Cache tab)The provider cache's hit rate today, tokens read and written, AI units, a table per model and per client, and the moments the cache was lost with the likely reason
Savings (Overview)What the proxy's techniques saved and cost, each figure marked measured or estimated, costs counted, and the net, which can be negative. Always shown next to what you actually spent (measured) and what you would have spent without them (spent plus the net). The net itself only ever totals the prompt cache and trimming, less Maple's own costs (cache-warming pings included) — a fixed choice, no setting changes it; a couple of other techniques are shown on their own line but held out of the net until their own estimate can be checked against a real bill
Search by meaning (Models & routing)A status line (what answers, or what is wrong and how to fix it); this machine's memory, CPU cores and system; the engine switch. Built-in (Go): both models with their size, licence and a note when the machine is below what a model is comfortable on, Download with progress and Cancel, Use this model, Remove, and the Hugging Face token a gated model needs. Your own server: base URL, model, optional API key, Test and Save and use
Protect this page (Security & access)An optional password for this page, off by default: Turn on (type it twice), change it, Sign out other browsers, Sign out, Turn off. See Protect the setup page with a password
Recent activity (Security & access)Sign-ins, token changes and switches
What's configured (Overview)Each basic feature on, off or needing attention, then the features you set up, and one line naming the rest, with a link to Set up more
Every setting (Advanced)Every setting, grouped by tab, with a filter. A form for the settings without a card (each with when it applies, its default and any environment variable that overrides it), Check and Save; the rest listed with where to change them. The raw configuration editor below it
Set up moreCards that start sharing with a team, hubs and chaining, single sign-on, monitoring, several replicas and the MCP hub

Saved settings apply to the very next request with no restart, except those marked restart required. The page checks every value with the same rules the proxy uses at start-up, and points at the field that is wrong. Saving changes only the settings you changed in config.yaml, so hand-written comments are kept (see above for the one exception).

Single sign-on for the setup page #

For teams: admins sign in to the setup page with their company account, on an address of its own, and developers too when developer sign-in is on. Off unless setup_page.sso.enabled is true. Set on the Single sign-on tab's wizard on the proxy's own machine (never through single sign-on), or in config.yaml. Read at start, except the admins, groups_claim, password, session_lifetime, self_view, people and developers keys, which apply on the next request. The guide, with each provider's steps: Single sign-on for the setup page.

KeyDefaultWhat it does
setup_page.sso.enabledfalseTurns single sign-on on
setup_page.sso.provideroidcoidc (Google, Microsoft Entra ID, Okta, any OpenID Connect provider) or github
setup_page.sso.namethe provider'sThe name on the sign-in button
setup_page.sso.issuerThe OpenID Connect issuer, https://
setup_page.sso.github_urlhttps://github.comGitHub Enterprise Server's address
setup_page.sso.client_idThe client (application) id
setup_page.sso.client_secretA ${secret:NAME} reference (maple-proxy secrets set sso/client_secret)
setup_page.sso.redirect_urlhttps://<host>/sso/callback, as registered with the provider; never this machine
setup_page.sso.listenThe address the page is served on for single sign-on, behind your load balancer
setup_page.sso.tls_cert_file, setup_page.sso.tls_key_fileServe listen with TLS
setup_page.sso.insecure_backendfalseAllow listen off this machine without TLS, inside a network that is yours alone
setup_page.sso.scopesScopes besides openid email profile
setup_page.sso.admins.emailsVerified email addresses that are admins
setup_page.sso.admins.domainsEmail domains whose verified addresses are admins (exact; not for GitHub)
setup_page.sso.admins.groupsGroups-claim values (GitHub: org or org/team) that are admins
setup_page.sso.admins.subjectsAccount ids (sub; GitHub: numeric user id) that are admins
setup_page.sso.groups_claimgroupsThe ID token claim the groups are read from
setup_page.sso.passwordoffallowed also accepts the page's password there
setup_page.sso.session_lifetime1hHow long a sign-in lasts, 5m to 12h
setup_page.sso.self_viewoffon lets people see their own usage by signing in
setup_page.sso.peopleEmail to person id, for the self view (and, with developer sign-in, who an address is)
setup_page.sso.developers.onboardingoffDeveloper sign-in: off, approve (an admin accepts each new developer) or auto
setup_page.sso.developers.domainsEmail domains whose verified addresses may sign in as developers (not for GitHub)
setup_page.sso.developers.groupsGroups (GitHub: org or org/team) whose members may sign in as developers
setup_page.sso.developers.teams[].group, setup_page.sso.developers.teams[].teamGroups to teams, in order: a new developer's team (a team set by hand is kept)
setup_page.sso.developers.token_days30How long a developer's own token lasts, 1 to 90 days
setup_page.sso.developers.max_tokens5How many live tokens a developer may hold, 1 to 20
setup_page.sso.developers.proxy_url, setup_page.sso.developers.anthropic_urlfrom server.allowed_hostsThe addresses developers' tools use, in their connect lines; proxy_url is also where a proxy signed in with a company account sends their requests (maple-proxy chain connect --sso, the setup page's Sign in with your company account): keep it on the single sign-on address's domain, over https, or the person is asked to confirm it

Observability export #

Prometheus metrics, an OpenTelemetry (OTLP) export and audit lines for a SIEM: counts, timings and labels, never content. All off by default; the setup page's Monitoring tab sets them up step by step, applied without a restart. The full guide, with what is exported and what never is: Metrics and telemetry export.

KeySetup pageDefaultWhat it doesHelps
metrics.prometheusMonitoringoffon serves /metrics (Prometheus text format) on the setup page's address, and on the OpenAI-compatible address to a token with the metrics scope when that address is reachable from other machinesEffective
metrics.per_personMonitoringoffon adds person and team labels to the request and AI-unit counters and to spans: more series, and the metrics then name peopleEffective (a trade-off)
otel.endpointMonitoringnoneThe OpenTelemetry collector's http:// or https:// address; setting it turns the OTLP export onEffective
otel.protocolMonitoringgrpcgrpc or http (HTTP/protobuf)Effective
otel.headersMonitoring, OpenTelemetry, Headers (the value typed once, to the secret store)noneHeaders sent with every export; one carrying a credential must be a reference; references may only be ${secret:otel/...} (what the page writes, or maple-proxy secrets set otel/<name>), ${env:OTEL_...} or ${env:MAPLE_...}, never a variable holding another credential (MAPLE_SECRET_* other than MAPLE_SECRET_OTEL_*, MAPLE_STORAGE_KEY, MAPLE_POSTGRES_DSN, MAPLE_REDIS_URL, MAPLE_WEBHOOK_*)Efficacious
otel.tracesMonitoringonOne span per request, metadata onlyEffective
otel.metricsMonitoringonThe /metrics figures, once a minuteEffective
otel.logsMonitoringoffon also sends the proxy's own log lines; audit events are sent whenever the export is onEffective
otel.insecure_httpMonitoring, OpenTelemetry, Plain http on a trusted networkoffHeaders are never sent over plain http:// to another machine: such an export is refused unless this is on (a network you trust)Efficacious
otel.service_nameMonitoring, OpenTelemetry, Service namemaple-proxy (or OTEL_SERVICE_NAME)The service.name the export carriesEffective
log.audit_linesMonitoring (MAPLE_LOG_AUDIT)offon writes each audit event (tokens made or revoked, refused requests, settings written, sign-ins, MCP hub calls) as a JSON line on standard output, secrets removedEfficacious

Containers and replicas #

For running the proxy in a container or as several replicas; see Docker and Kubernetes. They are read when the proxy starts, and none of them is on the setup page: storage names where secrets come from and is never shown there. The environment variable in brackets wins over the file.

KeySetup pageDefaultWhat it doesHelps
storage.modeConfig file (MAPLE_STORAGE_MODE)diskdisk: everything in files, as always. central: several replicas share PostgreSQL (what lasts) and Redis (what is shared and short-lived), the recommendation for several replicas. redis (2.3): several replicas share one Redis that keeps its data and no PostgreSQL; the proxy refuses a Redis without appendonly yes and maxmemory-policy noeviction (see without PostgreSQL)Effective
storage.postgres_dsnConfig file (MAPLE_POSTGRES_DSN)noneCentral mode: the PostgreSQL connection string, as a ${secret:...} or ${env:...} reference. Refused in redis modeEffective
storage.redis_urlConfig file (MAPLE_REDIS_URL)noneCentral and redis mode: redis:// or rediss://, as a referenceEffective
storage.encryption_keyConfig file (MAPLE_STORAGE_KEY)noneCentral and redis mode: required, exactly 64 hex characters (openssl rand -hex 32); every replica uses the same one, to encrypt what goes to Redis, to sign the shared settings and to derive the keys the replicas share. With storage.settings: postgres, give it as a reference or in the environment: written into config.yaml itself (which is then kept in the shared store) it is refused, as are passwords in postgres_dsn and redis_urlEfficacious
storage.settingsConfig file (MAPLE_SETTINGS_SOURCE)postgresCentral mode: postgres (recommended and the default; central, its 2.0 name, means the same) keeps config.yaml and the access tokens in PostgreSQL, run by every replica and edited on the setup page; file takes them from the file (a ConfigMap) and the page refuses changes. See how settings reach every replica. Redis mode: unset (or redis) keeps them in Redis, edited on the page; file as above; postgres is refusedEfficacious
storage.settings_seedConfig file (MAPLE_SETTINGS_SEED)noneCentral mode with postgres (or redis mode with settings in Redis): a config.yaml (a ConfigMap's file) copied into the shared store when it holds none yet, at the first start; never read again after thatEffective
storage.settings_check_secondsConfig file (MAPLE_SETTINGS_CHECK_SECONDS)2Central mode with postgres: how often a replica confirms it runs the store's current settings (at most 10). One that cannot confirm it for about three checks is not ready until it canEffective
storage.ready_requires_same_configConfig file (MAPLE_READY_REQUIRES_SAME_CONFIG)falseCentral mode: true makes /readyz say not ready on a replica whose settings differ from those most running replicas run, once that has lasted two minutes (a half-rolled ConfigMap, a pod edited by hand). The samples turn it onEffective
storage.budgets_when_downConfig file (MAPLE_BUDGETS_WHEN_DOWN)closedCentral mode, PostgreSQL away (redis mode: Redis away, or not keeping its data): closed refuses requests of people with a budget; open lets them through, uncountedEfficacious
storage.retention_daysConfig file (MAPLE_STORAGE_RETENTION_DAYS)server.usage_retention_daysCentral mode: how many days of usage and events PostgreSQL keeps; one replica deletes older ones daily. Keep the whole history elsewhere with a lake (see Kubernetes). Redis mode: how many days of usage, events and audit entries Redis keeps (in memory: size Redis for them)Efficient
storage.spool_max_recordsConfig file (MAPLE_SPOOL_MAX_RECORDS)2000Central mode, PostgreSQL away (redis mode: Redis away, or not keeping its data): how many usage lines a replica keeps in memory until it is backEfficient
log.formatConfig file (MAPLE_LOG_FORMAT)text (json in the container image)json writes one JSON object per line on standard output, requests includedEfficient
log.levelConfig file (MAPLE_LOG_LEVEL)infodebug, info, warn or error (JSON logs)Efficient
log.usage_linesConfig file (MAPLE_LOG_USAGE)offon also writes each usage record and event as a JSON log line, for a log stackEfficient
images.resize_memoryConfig file (MAPLE_IMAGES_RESIZE_MEMORY)25% of a container's memory limit; none on a machineHow much memory image resizing may take at once: a share (25%) or a size (256MiB)Effective
images.max_pixelsConfig file (MAPLE_IMAGES_MAX_PIXELS)what resize_memory allows, at most 50 megapixelsThe largest image resized at all; a larger one is sent as it cameEffective

Other variables for containers: MAPLE_CONFIG (the config file), MAPLE_OPENAI_LISTEN, MAPLE_ANTHROPIC_LISTEN, MAPLE_WEBUI_LISTEN (addresses; off for no setup page), MAPLE_ALLOWED_HOSTS (more host names, comma-separated), MAPLE_TRUSTED_PROXIES (more server.trusted_proxies, comma-separated), MAPLE_SECRETS_BACKEND=mounted with MAPLE_SECRETS_DIR (secrets from mounted files and MAPLE_SECRET_* variables), MAPLE_PROXY_ID and MAPLE_PROXY_INSTANCE (the proxy and this replica), MAPLE_EMBEDDINGS_DIR (where models are kept), MAPLE_DRAIN_DELAY, MAPLE_SHUTDOWN_GRACE and MAPLE_SSE_KEEPALIVE (stopping and streams), MAPLE_PROBES=on (/healthz and /readyz outside a container), MAPLE_MCP_HUB=embedded (a replica that serves the MCP hub itself) and MAPLE_BUDGET_RESERVATION_TTL (how long a stopped replica's running requests still count against a budget, 2 minutes).

Commands #

maple-proxy with no command starts the server. The others:

CommandWhat it does
maple-proxy serveStart the proxy (the default). Flags: -config a config file; -logs where logs go (false, true, stdout, or a file path); -log-bodies also log prompt and answer text, which is off by default because a prompt to a coding agent is source code
maple-proxy auth login <provider>Sign in to github-copilot (a browser flow), or with an API key to anthropic, xai (Grok) or gemini (Gemini API). auth status shows what is signed in, auth logout <provider> forgets a credential
maple-proxy auth openrouterSign in with OpenRouter to make a key, kept in the keyring: opens the browser (--no-browser prints the link; --headless asks for the code OpenRouter shows; --as NAME for a second account). See Sign in
maple-proxy providers discoverLists the model servers running on this computer (Ollama, LM Studio, a llama.cpp server, oMLX, Lemonade, Unsloth Studio), found on their usual ports at 127.0.0.1 and ::1 only, with their models, and says which are already providers. Adds nothing unless you pass --add, which adds each server that is not a provider yet (one that needs an API key is listed, not added). --json for a script. See Connect a model server
maple-proxy secrets statusWhere each secret is stored, never its value. secrets migrate moves keys out of config.yaml into the secret store; --dry-run shows what would move. secrets set otel/<name> stores one line read from standard input, for otel.headers; secrets set sso/<name> the same for setup_page.sso.client_secret
maple-proxy metrics token <label>Makes an access token with the metrics scope, shown once, for a Prometheus on another machine: it reads /metrics and nothing else. See Metrics and telemetry export
maple-proxy cacheThe Cache card in a terminal. --recent lists the last requests, --json gives raw figures, --addr names the setup address
maple-proxy healthThe Health card in a terminal: each provider and model the proxy has sent requests to, its state (healthy, degraded or demoted), its error rate against its usual rate, latency and time to first output, and why its state last changed. --watch prints it again every few seconds (--every 5s) until you stop it, --json gives raw figures, --addr names the setup address. See Provider health
maple-proxy health reset [provider/model]Clears what health remembers about a model, so a demoted model is healthy again with a fresh window (a demotion is kept across a restart). A provider id clears all its models; with nothing, every model. The Health card's Reset buttons do the same. See Provider health
maple-proxy alerts webhookThe alert webhooks: list, add <name> (the address, and with --sign a signing secret, read from standard input; --format slack|teams|json, --audience, --allow-private, --allow-http-loopback), rm <name> and test <name>. See Alerts and forecasts
maple-proxy cache probeSends the same small request twice and prints what each cost and how much came from the cache: a check you can run on your own account. It says what it will send and may spend a few AI units. -model, -tokens, -addr, -json
maple-proxy savingsThe Savings card in a terminal: --json, --addr
maple-proxy usage statusWhere the usage log is, whether it is on, how many days it keeps, and how much disk its daily files take (with the undated file from earlier releases, if any, counted apart, and an estimate at the retention limit). --path to look at another log
maple-proxy usage exportWrite your usage log (every rotated file, or a --since/--until UTC-day range of them) to a CSV or Parquet file: --format csv|parquet, --out FILE, --path to set the file directly instead of reading it from config.yaml (which, unset, means the default place). See Your usage data
maple-proxy usage pruneDelete rotated usage-log files older than --keep-days N. Lists what it would delete first; nothing is removed without --yes
maple-proxy usage cache-potentialHow many requests in your usage log had an identical earlier request (the same request, from the same client, to the same provider account) recent enough for response_cache to have answered it, in total and by client and model, with what those repeats cost (measured, from their own lines). --days N (default 7), --window 5m (the response_cache_ttl you would use), --json, --path. An upper bound: the log cannot say whether a request was repeatable or how its answer ended. Only requests recorded by this release onward can be compared
maple-proxy usage alertsThe alerts that fired, newest first, and whether each is still in force (from the events log). --since DAY (default: the last 7 days), --format table|json, --path. See Alerts and forecasts
maple-proxy usage forecastThe recent daily rate of spend (estimated: the median of the last 7 complete UTC days, with a range), how a typical day compares with each budget, and with --left N (and --resets DAY) when that much runs out at that rate. Hidden with fewer than 3 days of usage. --metric ai_units|cost_estimated|requests|list_cost_usd (list_cost_usd: estimated dollars, with each monthly dollar budget), the usage query filters except the time range, --format table|json, --path
maple-proxy usage compareTwo windows of your usage side by side, per request: --before A..B --after C..D (UTC days, both included), or --around a setting's name or a time with --window 7d. Takes the usage query filters except the time range, --force, --format table|json, --path. Measured on your traffic, observational, not a controlled test; refuses thin or poorly matched windows. See Compare before and after
maple-proxy usage auto-reportHow requests routed by auto turned out, per weight and model: errors, fallbacks, quick retries, switches after, conversation length. Takes the usage query filters (default --last 7d), --include-direct, --min-requests N, --format table|json, --path. Measured and observational
maple-proxy usage cache-missesWhy the provider's cache missed, from your usage log: how often it missed by client, client version and person, the most common reasons with plain advice for each, and an estimated cost of the misses (from prices seen on your own requests; misses on a model whose prices were not seen are counted, not priced). Takes the same filters as usage query (--last 7d, --agent claude-code, ...), --top N reasons, --limit N rows per table, --format table|json, --path. See Why the cache missed
maple-proxy usage schemaPrint the usage record's schema: --format json-schema (one log line), --format duckdb (column types), or --format sql (default: a DuckDB view named usage over the daily files, over an export with --source csv|parquet --path FILE, over the monthly files with --source parquet-monthly, or over the shared tables of central mode with --source postgres --dsn-env NAME). See The usage record schema
maple-proxy usage compactPack the usage log's closed days into one Parquet file per month in its analytics folder; only months whose days changed are written again. --month YYYY-MM, --rebuild. See Lots of history?
maple-proxy usage duckdbBuild or refresh maple_usage.duckdb (tables usage and events, and the maple.* views) with your duckdb command line; a refresh loads only what the daily files gained. --out FILE, --refresh, --rebuild, --dry-run, --duckdb PATH
maple-proxy usage lakeCreate or refresh a DuckLake of your usage (--source files on this machine, or --source postgres --dsn-env NAME in central mode), --maintain for the daily upkeep, --emit-sql setup|move|maintain|attach to print the SQL for a scheduled job or an analyst, --dry-run to estimate what it would write. A lake whose catalog is in PostgreSQL (--catalog-dsn-env) needs --source said; a lake filled from one source refuses the other unless --allow-mixed-sources. See The Maple data lake
maple-proxy embeddings listThe models for search by meaning, which is installed, their licences, and this machine's memory and cores with a note for any model it is below comfortable for. It also says which model the embeddings setting in config.yaml (or the file given with --config) chooses. Models are always kept in the config folder's embeddings/, whichever config file is used
maple-proxy embeddings install [name]Download a built-in model (default bge-small-en-v1.5; or embeddinggemma-300m, which needs HF_TOKEN or a token saved on the setup page) at its fixed revision, check every file against its built-in checksum, and install it. Ctrl-C cancels and leaves nothing behind. embeddings remove <name> deletes an installed model
maple-proxy embeddings testSend one short text to the embeddings server in config.yaml (embeddings.engine: server) and print the vector length, or what went wrong and how to fix it
maple-proxy embeddings cache statusThe embeddings cache: on or off, how many vectors it holds and their size, and how often it answered since the proxy started. It asks the running proxy; when none answers, it counts the files on disk. --addr, --json
maple-proxy embeddings cache clearDelete every cached vector, in memory and on disk. When no proxy is running, it deletes the files
maple-proxy storageSeveral replicas with shared settings in PostgreSQL (storage.settings: postgres): import-config [--from config.yaml] [--access access.json] [--force] copies files into PostgreSQL, where every replica runs them (refused when it holds a different copy, unless --force), and export-config [--out config.yaml] [--access-out access.json] [--force] writes PostgreSQL's copy back to files, readable by their owner only. In storage mode redis both work against the settings kept in Redis (refused while Redis does not keep its data durably)
maple-proxy setup-passwordThe setup page's optional password: status, set (asked twice, not shown; --stdin reads one line from a pipe) and reset (removes it, so the page is open again; asks first unless --yes). A running proxy picks up the change at once
maple-proxy peoplePeople on this proxy: list (budget use, spend, tokens by label, and proxy tokens tied to nobody; --format json, and the usage filters, default the last 30 days), add <id> [--team T], rm, team <id> <team>, tie-token <id> <token-id>, untie-token, budget <id> --daily N --monthly N [--daily-usd D] [--monthly-usd D], models <id> --allow a,b, accounts <id> --accounts a,b [--only], self-view on|off, default-accounts a,b. Tokens are given by id, never the token itself. See Teams
maple-proxy tokenAccess tokens in a terminal: add <label> [--person <id>] [--scope proxy|metrics] (shown once; --person ties it to that person at once), list (id, label, scopes and person; --format json; never the token), revoke <id> (and unties it from its person). Only the proxy and metrics scopes; remote control, chaining and the MCP hub have their own. See Teams
maple-proxy teamsTeams: list, add <id>, rm, budget <id> --daily N --monthly N [--daily-usd D] [--monthly-usd D], models <id> --allow a,b, accounts <id> --accounts a,b [--only]
maple-proxy mcp-hubThe experimental MCP hub: status, list, add NAME -- COMMAND [ARG...] or add NAME --url URL (a command needs a terminal), rm NAME, enable/disable (the hub, or one server by name), token LABEL (an mcp-hub access token, shown once), serve (the hub alone)
maple-proxy chainChained proxies: status (this proxy's id and name, each hub above with whether it answers and how many hubs are above it, the people inherited from the parent, and what proxies below sent up; --format json), token LABEL (a chain token, with the proxy and proxy-chain scopes, for a proxy that will use this one as its hub, shown once; --proxy <id> binds it to that proxy from the start, --person <id> ties it to a person whose rules hold for everything that proxy sends), token show (each chain token's id, label and bound proxy, never the token), token unbind <id>, connect --sso <sign-in address> (signs this proxy in to a hub with your company account; --name, --models, --models-url, --wait) and disconnect (ends that sign-in; --name, --keep-provider). See Which setup do I need?
maple-proxy audit tailThe newest entries of the audit logs: tokens made and revoked, keys saved, refused requests. -n how many, --json
maple-proxy chatSend one prompt and print the answer, for a quick check that a model responds. -model and -prompt are required
maple-proxy updateInstall a newer release. --check reports only
maple-proxy healthcheckAsks this machine's or container's proxy whether it is ready (/readyz; --live asks /healthz) and exits 0 or 1: the container image's health check
maple-proxy versionThe version and how it was built
maple-proxy licensesThe licences of the software inside the program. --summary lists the components

mplp is a short name for maple-proxy.

Response headers #

The proxy adds these to responses so you can see what happened to a request.

HeaderMeaning
X-Maple-First-Output-TimeoutOn the model list (GET /v1/models): the longest time, in seconds, the proxy waits for any listed model's provider to start answering (providers[].first_output_timeout_seconds). The proxy sends a chat answer's headers only once the model has started, so a client should wait at least this long; Maple Harness does
X-Maple-Served-ByThe provider and model that answered, for example github-copilot/gpt-6-sol. For Copilot Auto and Copilot Fusion, the model Copilot chose
X-Maple-RouterFor a request for auto: the weight the proxy judged it to be and the name it went to, for example auto: heavy -> auto-heavy (see Auto mode at the proxy). For Copilot Auto: the models Copilot offered, and whether Copilot chose the model for this request or the account's default model was used (with the reason). Both, separated by ;, when a weight goes to Copilot Auto. When the model that answered is one provider health has demoted: health: would demote <provider>/<model> (<why>), or with health_failover: on, health: <provider>/<model> demoted (<why>). Model names, counts and failure classes only
X-Maple-FusionOn a Copilot Fusion High or Max request: its place in the turn, for example high; cascade; phase=escalation; outcome=escalated; reviews=2; id=fusion-…: the tier, how the turn is worked, this request's part (solver, escalation, repair, revision), how the turn ended (on its last request), the scores of the reviews made for this request, and the turn's id. Labels and scores only. It also lists the request's other calls (calls=judge:0.620:u,…: the step, the AI units Copilot stated and u when Copilot was told you started it, which it counts as a premium request; held marks an answer a review is deciding on) and who Copilot was told started the request's own call (self=u or self=a).
X-Maple-PromotionWhen the provider that answered runs a promotion that ends within three days: <id>; ends=<time>; percent=<n>; <the provider's message>. Each request through it will cost more after it ends; Maple Harness says so once
X-Maple-Fallback-FromPresent when a fallback answered: the model that was passed over, and why
X-Maple-Cachehit, partial, miss or lost: how the provider's cache did. Not sent on streamed responses
X-Maple-Cache-Read, X-Maple-Cache-WriteTokens read from and written to the cache, where the provider reports them
X-Maple-Cache-ResponseOnly while response_cache is on: hit (a saved answer; nothing was sent to the provider, so the answer reports no tokens and no cost), miss (sent to the provider; the answer may be saved) or bypass (not a request the cache answers). Sent on streamed responses too. A client may send X-Maple-Cache: allow on a request to say a saved answer is fine for it
X-Maple-Prefix-StabilizedWhat the prefix stabiliser changed in the request, if anything
X-Maple-Tool-Results-TrimmedHow many old tool results were replaced, and about how many tokens
X-Maple-ImagesHow many images were resized or replaced by a note, and about how many image tokens that left out (an estimate from the provider's published rule)
X-Maple-AlertOnly while a spend alert is in force: one value per alert, <id> <level> <message>, for example budget.80@budget:provider:copilot@2026-10-08 warn copilot has used 80% of today's budget (160 of 200 requests); it resets at 00:00 UTC. The id stays the same for the alert's whole period, so a client can show it once. Provider ids and figures only
X-Maple-InitiatorSent by Maple Harness, with the value agent, on a request it makes on its own (a check after an answer, a summary): the proxy then tells GitHub Copilot the request is the agent's, not a new turn of yours, and Copilot Auto and Copilot Fusion keep it in the current turn. It can only mark a request the agent's, and is honoured only from a tool on the proxy's own machine (without an access token) or from a chained Maple proxy; from anyone else behind a shared proxy it is ignored. The usage log records who started each request (initiator).
X-Maple-Model-SwitchSent by Maple Harness on the first request after you switch model, with the value user and nothing else, so maple-proxy usage auto-report can say what followed a choice of auto
X-Maple-Snapshots-TrimmedHow many browser page snapshots were recognised, how many were sent as changes only or cut, and about how many tokens that left out
X-Maple-Context-TrimmedPresent when the context guard dropped old turns to fit the model's window
X-Maple-Output-NoteOn an answer that is not streamed, when it needs saying how the answer ended: a reasoning model used its whole output limit on reasoning before any answer. A streamed answer carries the same note as output_note in its usage. See When the output limit goes on reasoning
X-Maple-ClientSent by the harness so its requests can be told apart from other tools' in the Cache card
X-Maple-SessionSent by a client (the harness sends it automatically) so its requests, and any subagent's, group together on the Sessions card
X-Maple-Usage-RowsOn a download from the setup page's Usage data card: how many requests the exported file holds
X-Maple-Usage-SchemaOn the same download: the version of the usage record schema the file follows
X-Maple-FailureOn an error answer to a chained proxy only: the failure's class (daily budget spent, quota exhausted, rate limited, overloaded, server error, unreachable, chain loop, too many hops), so the proxy below falls back the right way
X-Maple-Chain-Person, X-Maple-Chain-Team, X-Maple-Chain-Origin, X-Maple-Chain-Via, X-Maple-Chain-Ids, X-Maple-Chain-Hops, X-Maple-Chain-Request, X-Maple-Chain-ProofRequest headers a proxy sends to its hub: who asked, the first proxy, the path, the hop count, the request's id, and, for a person a hub above defined, a proof that they signed in with their own token (never the token). A hub reads them only from a proxy-chain token and removes them from every other request
X-Maple-SettingsOn a refused change on the setup page of a proxy whose settings come from its configuration files (storage.settings: file): read-only
Idempotent-Replayedtrue on an answer played back for a repeated Idempotency-Key (see Kubernetes)
X-Maple-Config-BaseOn the setup page's raw configuration: which version of the file it shows. Sent back with a save, a copy that is out of date is refused, so it cannot undo a change made since
X-Maple-Config-PathSent by a maple-proxy command that tells the running proxy about a change it saved: the configuration file it wrote. The proxy applies the change only when that is its own file, and otherwise keeps its configuration

Files and environment #

WhereWhat
versionThe configuration file's format version, currently 1
~/.config/maple-harness/config.yamlThe proxy's and the harness's settings
~/.config/maple-harness/embeddings/The installed built-in model for search by meaning, one folder per model, and the cache of computed vectors in cache/, private to you
~/.config/maple-harness/setup-page-password.jsonThe setup page's password as a salted hash, and its signed-in browsers, private to you. Absent when the page has no password
~/.config/maple-harness/access.jsonAccess tokens (hashed) and the remote-control switch. Managed by the setup page
~/.config/maple-harness/chain-bindings.jsonWhich proxy each proxy-chain token is bound to, private to you. Absent until a chain token is bound. Kept apart from access.json so that going back to a 1.x release does not unbind them
MAPLE_DUCKDB (environment)The duckdb program the proxy's analytics refresh and the usage duckdb and usage lake commands run, as an absolute path; --duckdb overrides it. Without it, duckdb on the PATH. A relative path, a program found only through the current folder, or a program or folder any user can change is refused. The program gets a minimal environment, not the proxy's (see the data lake's troubleshooting)
Your system keyringProvider keys and sign-ins. Without a keyring, a private file with the same protection, and the proxy says so
~/.config/maple-harness/usage/maple_harness_proxy_usage_ledger-YYYY-MM-DD.jsonlThe usage log, one file per UTC day, private to you (or <usage_ledger>-YYYY-MM-DD.jsonl when server.usage_ledger names another path; none when it is off). One JSON object per request (see Your usage data): at, duration_ms, requested, model, provider, streamed, tools, messages, input_tokens, output_tokens, cached_tokens, cache_write_tokens, ai_units, error, client, agent, surface, conv, fallback, cache_class, cache_reason, and since schema version 2 schema_version, session, warming, cost_estimated, cost_currency, priced and the per-request cost and savings estimates (types and meanings: the usage record schema). Never prompt or answer content

Read next: Commands and keys, Harness settings, and Settings by goal.

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