Harness settings #
On this page
- In plain words
- Settings at a glance
- Per-project overrides
- Model choice
- Long conversations
- Permissions and safety
- Runaways and long output
- Cost preview
- Language servers and shell writes
- Tools, skills and hooks
- Subagents and remote control
- Notifications
- Housekeeping and appearance
- Where the harness finds the proxy
- An annotated example
The harness reads the settings under harness: in config.yaml (usually ~/.config/maple-harness/config.yaml).
The proxy's settings are in the same file and are covered in the Proxy settings. Changes
under harness: apply the next time you start the harness; the proxy picks up its own changes without a restart.
Every setting has a Helps column, because each 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, and the safe choice is the default.
- Effective: whole tasks succeed: the right model, and waste stopped before it grows.
A tag appears only where it is true, and trade-offs are stated. Nothing here is a promise about your bill:
measure your own tasks. Keys are written relative to harness:, so sandbox.mode means
harness.sandbox.mode.
In plain words #
- What it is. Every setting of the agent, the part of
config.yamlunderharness:. - What to do. Most people never edit it:
/settingsin a session changes the common ones, and/configuration set <key> <value>any one. A project can override some of them in its own folder. The proxy's settings are a separate page, and on its setup page.
Settings at a glance #
| Key | Default | Helps |
|---|---|---|
default_model | none | Effective |
compress_ | off | Efficient |
compress_model, compress_scope | none (chosen for you), same-account | Efficient, Efficacious |
digest_ | on | Effective |
auto_model, auto_model_map, auto_avoid, auto_, auto_ | off, none, *-codex*, client, heavy | Efficient, Effective |
fusion_ | none | Efficient |
effort, disable_ | none, off | Efficient |
permission., permission. | ask, shipped rules | Efficacious |
sandbox.* | off locally, auto while shared | Efficacious |
file_policy.* | on | Efficacious |
loop_, loop_, loop_ | stop, 3, 6 | Efficient, Effective |
tool_ | 120 | Efficient |
disable_ | off | Effective |
max_ | 50 | Efficient, Effective |
ledger | off | Effective |
cost_preview, cost_, cost_ | off, 50000, unset | Effective |
lsp, lsp_servers[] | auto, none | Effective, Efficacious |
bash_ | warn | Efficacious |
subagents., subagents. | 3, 50 | Efficient, Effective |
delegates. and its delegates. settings | off | Effective, Efficacious |
notifications. | off | Effective |
remote. | off | Efficacious |
retention.* | 30, 5, off | Efficient |
proxy_logs | off | Effective |
first_ | follow the proxy (10 minutes, or longer for a slow local model) | Effective |
proxy.url, proxy.token, proxy., proxy. | none (the proxy on this machine), off | Effective, Efficacious |
Run /configuration in a session to see every setting's effective value, right now, and which file it came from.
/configuration set <key> <value> changes one and saves it to your global config.yaml — for example
/configuration set loop_guard.mode warn. Most settings here are read once when the harness starts, so a change
through /configuration applies the next time you start, not to the session you set it from; the response says so.
Per-project overrides #
A project can carry its own .mapleharness/config.yaml (or .mapleharness/config.json) that changes some of
harness:'s settings just for that project, on top of your global config.yaml. It only needs the keys it changes:
# .mapleharness/config.yaml, committed with the project
default_model: gpt-6-sol
loop_guard: { mode: warn }
Anything the project's file does not mention keeps your global value — setting loop_guard.mode above does not
reset loop_guard.warn_after or anything else. A list (mcp_servers, sandbox.hide, and so on) is the exception:
if the project's file names one at all, that is the whole list for this project, not an addition to your own.
notifications.* stays governed by your global config only, whatever a project's file contains: a notification
destination can be a command, and letting a cloned repository set one would let it run something whenever a
session finishes, needs approval, or fails.
proxy.* and proxy_logs are your global config's only too: they say where every request, and your proxy's
access token, are sent, and where a proxy the harness starts writes its log. A project's file that sets them gets
a note when the session starts, and the keys are ignored.
delegates.* is your global config's only as well: running your own Claude Code uses your sign-in and your plan,
which only you turn on.
cost_preview_confirm_above is also yours alone: a question before a costly message is a limit you set on your own
spending, so a project cannot add one or change it. A project may still turn cost_preview on for itself.
Since this file runs from a cloned repository, the first time you run the harness in a project that has one (or a
.claude/hooks.json, or a .mcp.json), it asks whether to trust it — naming exactly what it would run or apply.
Say no, or run non-interactively, and the project's file has no effect: the session runs on your global config
alone. maple-harness trust list | approve | forget manages the decision afterwards — the same one decision covers
hook files too; see Tools, skills and hooks.
Model choice #
| Key | Default | What it does | Trade-off | Helps |
|---|---|---|---|---|
default_model | none | The model or alias a session starts on. With none set, it is gpt-6-sol when the proxy serves it, else the first model that can use tools. If you name one the proxy does not serve, the harness starts on the first model it does serve that can use tools, and says which. auto hands the choice to the proxy, which picks the model for each request: a session's first message starts on the heavy model unless it reads as a short side job, and every request of one message stays on one model. See Auto in other tools, through the proxy | Effective | |
auto_model | off | Start with /model auto on: a model chosen for each message from what your provider serves, keeping your model when it fits | Choosing a model has a bill attached, so it is opt-in | Efficient, Effective |
fusion_ | none | AI units a Copilot Fusion High or Max turn may be billed before the rest of your turn runs on Copilot Fusion Standard; Maple Harness says when it happens, and your next message goes back to your model | A hard turn can finish on a cheaper tier, with no review | Efficient |
auto_model_map | none | Pin the model auto uses for heavy, medium and light work, for example heavy: gpt-6-sol. One global map; a name must be served by the provider you are on, or it is ignored with a note | You take over the ranking | Effective |
auto_avoid | ["*-codex*"] | Model-id patterns (case-insensitive) that auto never picks for you: models tuned for a different agent tool that tend to decline long tasks here. [] turns the default off. A model you chose yourself is never blocked | A pattern may hide a model you would have liked | Effective |
auto_ | heavy | Where auto starts a new message, before any work is under way: heavy or medium. Planning and questions that ask for judgement stay heavy | Medium is cheaper per request, but a hard task on a weaker model can cost the work; compare with maple-harness bench first | Efficient |
auto_ | client | client picks among what your provider ranks, as above. proxy still judges each turn here, but asks for it by a fixed name (auto_model_map's entries, or auto-heavy/auto-medium/auto-light) and leaves the proxy to decide the model: its defaults, or what you chose on its Auto mode card — see Auto mode at the proxy. Works with a provider that ranks nothing at all, once you choose its models there | The proxy serves auto-heavy, auto-medium and auto-light by itself only when one of its providers ranks its models; otherwise choose them on the card, or that weight's requests fail. maple-harness doctor checks this | Efficient, Effective |
effort | none | Start with a reasoning-effort level the model accepts | Higher effort thinks longer and costs more | Efficient, Effective |
disable_ | off | Start with thinking off | Faster and cheaper, at the price of harder problems | Efficient |
compress_ | off | Whether making room in a long conversation may ask a model for a written summary. off: never, so making room costs nothing; the record and the searchable history below carry the earlier turns. free: only a model that costs nothing, one on your own machine or network. on: any model, as described under Long conversations. Applies in auto mode too | free and on send the earlier conversation to the summarising model; on can spend credit | Efficient |
compress_model | none | With compress_with_model on, the model that summarises, tried after the model you switched away from. With none set, the harness picks the cheapest suitable model within compress_scope | A model you name is used even when a cheaper one would do, and even outside compress_scope, with a note | Efficient, Effective |
compress_scope | same-account | Where an automatically chosen summarising model may be. same-account: only the provider account your session is using. same-provider: any account of the same service. any: any model the proxy serves. A model on your own machine or network is always allowed, and a session on one is summarised only by such models unless this is any | Widening it can send your conversation to a service or account you did not pick for it | Efficacious |
digest_ | on | Whether the record kept in place of older messages also quotes, word for word, the sentences from earlier replies that read like a decision, a requirement, a fix, a cause or an open item. A small classifier built into the harness picks them; no model is asked and nothing is sent anywhere. off leaves them out | It can pick a sentence that is only chatter, and in a very small window the quotes take room that would otherwise list more files and requests | Effective |
Long conversations #
When a conversation outgrows the model's window, older messages leave the model's view. What leaves it is kept and searchable:
- Older parts of a long conversation stay searchable. Every message is stored, word for word, beside the
saved session before it leaves the model's view, and the model can look any of it up again with the
history_searchtool: by words, a file path, a tool, or a message number. A search returns a few short snippets, so it never floods the conversation. The store is part of the session:--continueand--resumebring it back, a/forkor/clonegets its own copy, and removing the session removes it. It stays on your machine with the same file permissions as the session. - In their place, a record built from the conversation itself: every request (the first one always), the
files read and changed, the commands run and whether they passed, the names of failing tests, what failed, and
the assistant's last words. It also quotes, word for word, the sentences from earlier replies that read like a
decision, a requirement, a fix, a cause or an open item (
digest_key_points). Credentials are replaced with a marker before it is written. It needs no model, no network and no credit, and it ends by telling the model which stored messages it replaces and thathistory_searchfinds them. - By default, that is all. Making room sends no request to any model, so it costs nothing, in auto mode or not. A short line in the conversation says a record was kept and that earlier turns are searchable.
- A written summary, only if you ask for one with
compress_with_model. Withfree, only a model on your own machine or network is asked. Withon, the harness asks, in order: the model you just switched away from (it has read this conversation already);compress_model, or when that is not set the cheapest suitable model withincompress_scope(a model on your own machine or network first); then the current model. A model already known to be out of credit, over its daily budget or rate limited is skipped without asking it. If the summary goes to a different provider or account than the one your session is on, a line in the conversation says where it went. The history is sent in pieces that each fit the model's window, and the answer streams, so a slow local model is not mistaken for a dead one. While this runs, the activity line says which model is summarising;Escstops it and leaves the conversation as it was./costlists each summary request, with the model, apart from your turns; with no summary request there is no such line.
The stored history is bounded: once a session's store grows very large, its oldest messages are dropped, and a
search says which messages are no longer there. A /fork to an earlier message copies only the stored history that
belongs to the messages it keeps. A session started under the name of one that was removed never sees the old
session's history.
If the proxy answers with a fallback that has a smaller window than the model you asked for, the harness works to the smaller window until your model answers again.
Permissions and safety #
| Key | Default | What it does | Trade-off | Helps |
|---|---|---|---|---|
permission. | ask | The starting mode: ask, auto or yolo. yolo is honoured only when you start with --yolo | Efficacious | |
permission., permission. | shipped rules | Rules matched in order: decision is allow, ask or deny, and deny is absolute in every mode. A pattern names a tool, or a tool with an argument such as bash(rm -rf*) | Broad allow rules ask less and protect less | Efficacious |
sandbox.mode | unset: off for a normal session, auto while a session is shared | Contains the bash tool. auto uses a backend when there is one and says so when there is not; strict refuses to run commands without one; off contains nothing | Contained commands see fewer files and, while shared, no network | Efficacious |
sandbox. | unset: allowed locally, denied while shared | deny cuts the network for contained commands; allow keeps it (installs and downloads then work) | Denying it breaks npm install and git clone | Efficacious |
sandbox., sandbox., sandbox.hide | none | More paths the sandbox may write, may read, or hides (absolute, ~/…, or relative to the project) | Efficacious | |
sandbox. | none | Environment variables that survive the scrubbing of secret-looking ones | Each one you allow is visible to contained commands | Efficacious |
sandbox. | off | on: while sandbox.mode is unset, contain commands whenever they run without a person approving them (auto or yolo mode, and helper agents in them); ask mode is unchanged. An explicit sandbox.mode always wins. See The shell sandbox | Contained commands cannot use hidden logins (git over SSH, gh, cloud tools, Docker) until you allow them | Efficacious |
file_ | on | Confines the file tools. off removes the confinement | Efficacious | |
file_ | hidden-only | hidden-only: read anywhere except places that hold credentials. project: only the project, the temp directory and extra_readable. anywhere: no limit, which is not safe | project blocks reading outside the project | Efficacious |
file_, file_, file_ | none | More places to hide; more places writes may go besides the project and the temp directory; more places reads may go under read: project | Efficacious | |
bash_ | warn | What the bash tool does with a command that writes a project file through the shell: warn runs it and adds a note pointing at the file tools; deny refuses and names the file; allow says nothing | The file tools show you a diff and run safety checks; a shell write does not | Efficacious |
What the sandbox does and breaks, and install commands for its backend, are in The shell sandbox. /sandbox shows the current state.
Runaways and long output #
| Key | Default | What it does | Trade-off | Helps |
|---|---|---|---|---|
loop_ | stop | What to do when the same problem keeps failing after different attempts: off, warn (one note to the model), or stop (the note, then the turn ends with a summary for you) | stop may end a run you would have let continue; warn never ends one | Efficient, Effective |
loop_ | 3 | How many similar failures before the note | Lower nags sooner | Effective |
loop_ | 6 | How many similar failures before the turn ends and asks for your guidance | Lower stops sooner | Efficient |
tool_ | 120 | How long a failing command's output may be before it is shortened to its start, the lines that say what failed, and its end. The exit status is always kept and the full output is saved to a file whose path is shown. 0 turns it off. Passing commands are never shortened | The model sees less of a long log, and can read the saved file if it needs the rest | Efficient |
disable_ | off | Stops the harness carrying a turn forward when the model describes a step without taking it, or declines a task it can do. Also turns off the checklist's completion check | Turning it off means you type "continue" yourself | Effective |
max_ | 50 | The most times one message is carried forward automatically. Then the turn stops with "Stopped: the model kept describing steps without taking them", leaving its last report as the answer; it also stops at once when the model, asked to carry on, describes the next step again instead of taking it. At most 1000 | Lower stops a model that keeps narrating sooner, and a long task may need you to type "continue" | Efficient |
ledger | off | auto keeps a checklist for a request that reads like a specification, checks each item before it is called done, and asks the model to carry on while any are open. See /ledger | One extra model call for such requests | Effective |
maple-harness --prompt runs that are stopped by loop_guard exit with status 3.
Cost preview #
Off by default, and quiet when on: it is shown only for the messages you asked about, never sent to the model, and never kept in the conversation.
| Key | Default | What it does | Trade-off | Helps |
|---|---|---|---|---|
cost_preview | off | Before a message is sent, shows about what its first request is likely to cost, always labelled estimated, with what the figure is based on. large: only when that request is at least cost_preview_large_tokens. on: for every message | One small read-only question to your proxy before each message it covers | Effective |
cost_ | 50000 | How large a request must be, in tokens, before large shows its estimate | Lower shows it more often | Effective |
cost_ | unset | Asks once before sending a message whose estimate is above this number, in the estimate's own unit (AI units, or dollars for a list price). Answer no and nothing is sent; the conversation stays as it was. Unset never asks. Works whatever cost_preview says | A --prompt run with no one to answer does not send such a message, and exits with status 1 | Effective |
How the figure is made and how to read it are in What /cost tells you.
Language servers and shell writes #
| Key | Default | What it does | Trade-off | Helps |
|---|---|---|---|---|
lsp | auto | With no lsp_servers, finds language servers from the project's marker files and PATH, and adds their errors to the result of each file write or edit, so the model fixes its own mistakes. off turns detection, the diagnostics and the lookup tools off | The first edit starts the server in the background, and a timeout adds nothing | Effective, Efficacious |
lsp_, lsp_, lsp_ | none | Name a server yourself, for example {extensions: [".go"], command: gopls}. When any are set, nothing is detected | You maintain the list | Effective |
The table of languages, marker files and install commands is in Language servers.
Tools, skills and hooks #
| Key | Default | What it does | Helps |
|---|---|---|---|
mcp_ | required | The server's name. Its tools are named mcp__<name>__<tool>, and a permission rule names one tool, such as mcp__github__create_issue (the bare create_issue also matches it, on every server) | Effective |
mcp_ | inferred | http or sse for a remote server. A command means a local one | Effective |
mcp_, mcp_, mcp_ | none | A local (stdio) server: the program, its arguments and extra environment | Effective |
mcp_, mcp_ | none | A remote server and the headers sent with every request (values may be ${env:NAME} or ${secret:name}) | Effective |
mcp_, mcp_ | off | Permit plain http off this machine, and a server on this machine or a private network. Off by default; a repository's own .mcp.json cannot set them | Efficacious |
skills., skills. | .claude/ in the project and your home | Where to load skills from, and the convention each directory follows (claude, opencode or npx) | Effective |
hooks.files | discovered | Hook files to load. Empty means the default places; hooks run shell commands, so treat a hooks file like a script | Effective |
graph.path | per project, under the config directory | Where this project's index is kept |
A remote MCP server is never connected to a link-local or cloud-metadata address, even with allow_private; the
exact addresses a trusted server needs can be allowed only with the environment variable MAPLE_MCP_ALLOW_ADDRESSES,
never from a config file. See Reaching cloud metadata or link-local services.
See Give other tools this project's knowledge for serving your project to other tools, and Subagents.
Subagents and remote control #
| Key | Default | What it does | Trade-off | Helps |
|---|---|---|---|---|
subagents. | 3 | How many subagents run at once (1 to 16). More wait for a free slot | A local model may not serve several at once | Efficient, Effective |
subagents. | 50 | The most turns any one subagent may take, whatever its own limit asks for (1 to 200) | Efficient | |
delegates. | off | on lets a session hand a whole task to your own installed, signed-in Claude Code, on this machine. See Delegate to your local Claude | It uses your Claude plan and its limits | Effective |
delegates. | read | What it may do: read (read and search files), edit (also edit and write files) or full (also run commands and fetch from the web). Your permission rules can only narrow it | More access, less you see before it acts | Efficacious |
delegates. | off | on lets it load the project's own .claude/settings.json, .claude/settings.local.json and .mcp.json (hooks, helper commands, MCP servers) | Those run as you, without asking | Efficacious |
delegates. | 20 | The most turns one run may take (1 to 200) | Efficient | |
delegates. | 15 | How long one run may take before it is stopped (1 to 240) | Efficient | |
delegates. | empty | The claude program to run: an absolute path (~/ allowed). Empty finds claude on your PATH. It must be a regular executable file outside the project, not writable by others. See Choose which 4 runs | Efficacious | |
delegates. | none | Extra options for claude -p, one per entry (--model sonnet). Only --model, --fallback-model, --effort, --max-turns, --max-budget-usd, --append-system-prompt and --add-dir, each checked; anything else is refused. See Extra options for Claude Code | --add-dir lets it read one more folder | Effective |
remote. | off | Lets a paired device start a session in yolo mode from the phone. Off unless you turn it on; gateway --allow-yolo does the same for one run | Every approval is skipped for that session | Efficacious |
Notifications #
Messages to your phone or desktop when a session needs approval, stops with an error, or needs your guidance.
They say which project and what happened, and nothing else: never a command, a file's content or an error's text.
Off until you list a destination. Try it with maple-harness notify test.
Separately from these, a session asks your terminal to show a desktop notification when a turn finishes or needs
your approval, in the form your terminal understands: foot, kitty, Ghostty, WezTerm, iTerm2 and Windows Terminal are
recognised, and other terminals get the most common form. Inside tmux, add set -g allow-passthrough on to your tmux
configuration so it reaches the terminal. For a notification that does not depend on the terminal, set
notifications.desktop: true, which uses notify-send on Linux and osascript on macOS.
| Key | Default | What it does | Helps |
|---|---|---|---|
notifications. | off | A notification on this machine | Effective |
notifications. | required | ntfy, webhook, command, desktop or bell | Effective |
notifications. | none | A label for the destination | |
notifications., notifications., notifications. | none | Where to send it, and any credentials. Write them as ${env:NAME} or ${secret:name} | Efficacious |
notifications. | off | Allow plain http to a host that is not this machine | Efficacious |
notifications., notifications. | none | A program to run, never through a shell. Arguments may hold {title}, {body}, {kind}, {session} and {url} | Effective |
notifications. | approval, error, stalled, alert and device | Which to send: approval, done, error, stalled, alert (a spend alert from the proxy, sent once per alert and only when one fires), device (a device for one session you made paired, or its session switched to auto or yolo). done must be asked for | Effective |
notifications. | 20s | How long a question stays open before it is worth a message, so answering at the keyboard sends nothing | Effective |
notifications. | 60s | How long a turn must run before done is sent | Effective |
notifications. | off | Add the tool's name to an approval message. Arguments are never included | Efficacious |
notifications. | 6 | The most messages in total per minute | Efficacious |
notifications. | none | The address a tap on the message opens | Effective |
notifications. | on | Whether the gateway may push to paired phones that turned notifications on in the web app. Nothing is sent until a phone subscribes | Effective |
notifications. | the project's page | The contact that push services see |
Housekeeping and appearance #
| Key | Default | What it does | Helps |
|---|---|---|---|
retention. | 30 | How old a saved session must be before cleanup treats it as old | Efficient |
retention. | 5 | How many recent sessions per directory cleanup always keeps | Efficient |
retention. | off | Run what cleanup --yes would, once a day, when a session starts | Efficient |
theme, theme_colors | the default theme | A colour theme by name, and per-role colour overrides | |
mouse | on | The mouse wheel scrolls in every state, a click opens one folded tool result or a subagent, and a drag selects text and copies it. Your terminal's own selection then needs Shift held (Option in iTerm2). false starts with the mouse off, which gives plain selection back, and the wheel scrolls only where the arrow keys do. /mouse on and /mouse off switch it while running | |
animations | on | How much the interface moves. on: a leaf in the theme's colours while the model thinks, a spinner with the tool's name while a tool runs, a soft shimmer on the working line, a cursor at the end of a streaming answer, the context meter easing to its new value, a gentle pulse on an approval question, and a small note when a long turn finishes. reduced: a still symbol for each state and nothing moves (the elapsed time still counts). off: as reduced, without the streaming cursor and the note. on is reduced automatically when NO_COLOR is set, TERM is dumb or the output is not a terminal, and draws fewer frames over SSH. Nothing is redrawn for animation while the session is idle, and output is never slowed down | |
image_paste | auto | Ctrl+V with a picture on the clipboard saves it into the project and puts its path in your message (macOS; Linux with wl-clipboard or xclip), and dropped pictures are attached. off pastes text only, and dropped pictures go in as paths | |
image_ | none | A command that reads the clipboard picture instead of the built-in reader, on macOS or Linux (for example pngpaste -). It runs directly, not through a shell (write sh -c '…' for one). If an argument contains {path}, the command writes the picture to that file; otherwise it prints the picture to its output. PNG, JPEG, GIF, WebP and BMP are accepted, up to 20 MB and 3 seconds. A non-zero exit or anything that is not a picture means there is no picture, and Ctrl+V pastes text | |
system_prompt | none | Text added to the harness's base instructions | Effective |
engineering_ | auto | Whether a short engineering-standards note is added: auto (only when the project has no AGENTS.md or CLAUDE.md), always or never | Efficacious |
engineering_ | built in | Replaces the text of that note | Efficacious |
theme also takes any of the following built-in names (/theme lists them the same way), or theme_colors can
override individual roles (accent, deep, light, text, muted, faint, ok, warn, err) on top of any of them:
- Dark:
maple(default),ocean,forest,mono,dracula,nord,gruvbox,catppuccin-mocha,tokyo-night,solarized-dark,monokai,one-dark,everforest,rose-pine,hackerman(the green-on-black terminal look, a community nickname rather than one published scheme) - Light, for a light terminal background:
maple-light,gruvbox-light,catppuccin-latte,solarized-light,one-light - Colour-vision-deficiency-friendly:
colorblind-dark,colorblind-light— the status colours (not just the accent) are chosen from the Okabe–Ito palette to stay distinguishable under red-green colour blindness, the most common form. This is a design choice, not a certification: nothing here has been tested against colour-vision simulation software. auto: on a machine running Omarchy, follows the desktop's own active theme (whateveromarchy theme currentreports), and keeps following it while Maple Harness runs: switch the Omarchy theme and Maple Harness's colours change within a couple of seconds, including what is already on screen. A desktop theme with a Maple equivalent uses it; one without (Kanagawa, for example) takes its colours from the Omarchy theme itself.theme_colorsstill applies on top. Choosing another theme with/theme <name>stops following until you choose/theme autoagain. Everywhere else, including a Linux machine not running Omarchy, macOS or Windows,autoismaple.
Most of the dark and light themes reproduce a well-known published colour scheme (Dracula, Nord, Gruvbox, Catppuccin, Tokyo Night, Solarized, Monokai, One Dark/Light, Everforest, Rosé Pine), so it looks the same here as it does in an editor or terminal already set up with it.
Where the harness finds the proxy #
| Key | Default | What it does |
|---|---|---|
version | 1 | The configuration file's format version |
server. | 127.0.0.1:11535 | The proxy's OpenAI-compatible address, which the harness talks to |
server. | 127.0.0.1:11537 | The proxy's Anthropic-compatible address |
server.webui | 127.0.0.1:11539 | The proxy's setup page, which /proxy and doctor use |
To use a team hub, sign your own proxy in to it (Join your laptop to a team hub):
the harness keeps these settings as they are. To use a proxy on another machine directly, set proxy.* (usually with
maple-harness proxy connect <url>, which stores the token for you). Unset, nothing changes: the harness uses the
proxy at server.openai_compat on this machine, its own: the normal way. Set, it is a proxy you connected to (an
advanced setup for CI and containers), even at a local address (an SSH tunnel, a port forward, a container's port). See
Connect the harness to a proxy, Teams, and
Which setup do I need? for when to use proxy.url and when proxy.trust_unchecked.
| Key | Default | What it does |
|---|---|---|
proxy.url | none | The address of a proxy run elsewhere, with its scheme, for example https://proxy.example:11535. The harness sends its requests there and never starts, stops or restarts that proxy; auth, savings and the quota line work through the proxy's setup page, so they run on its machine |
proxy.token | none | That proxy's access token, written only as ${secret:name} (the secret store) or ${env:NAME}. A token written out in config.yaml is refused. It is sent as Authorization: Bearer on every request; to a proxy on this machine without proxy.url, only once it proved it is yours, so for one that cannot, use maple-harness proxy connect |
proxy. | off | Allows plain http:// to a proxy on another machine, which sends the token where the network can read it. Use https, or a private network such as Tailscale or a VPN and then this |
proxy. | off | While the proxy on this machine is unverified (an older release, or one run as another user, in a container or with a different settings folder), the harness asks before a session starts and tools ask before every run. On, it does not ask and tools run as your rules say: for CI and containers. Nothing secret is sent to such a proxy and the Claude delegate stays off either way. MAPLE_TRUST_UNCHECKED_PROXY=1 does the same for one run. It never sends proxy.token: a proxy that needs a token is connected with maple-harness proxy connect. See Verified and unverified proxies and the CI recipes |
How long a request waits for the model to start answering:
| Key | Default | What it does |
|---|---|---|
first_ | 0: follow the proxy | How long a request waits for the proxy to start answering, which it does once the model's first output arrives. 0 follows the proxy: 10 minutes, or longer when the proxy says it waits longer for one of its providers (a model server you run waits 30 minutes by default; see providers[].first_output_timeout_seconds in Proxy settings). When the time runs out the request is asked again at most twice, then the turn stops with a message naming the model and this setting. Raise it, and the provider's, for a slow local model on a long write |
The harness starts the proxy itself if nothing is listening. That proxy keeps no log unless you ask for one:
| Key | Default | What it does |
|---|---|---|
proxy_logs | off | Where a proxy the harness starts writes its log. on: logs/proxy.log in the configuration folder (usually ~/.config/maple-harness/logs/proxy.log). A path (absolute, or starting with ~/): that file. off: no log, and its output is not kept |
The file is created readable only by you, and when it has grown past 10 MB the harness moves it to
proxy.log.1 (replacing an older one) the next time it starts the proxy. It is the proxy's own log, the same as
maple-proxy serve --logs <file>: one line per request and no prompts or answers. /proxy shows where it is,
and /proxy logs (or /proxy logs 100) shows its last lines. A proxy you started yourself, or one running as a
service, is not affected. The setting is read when the harness starts, so after changing it start the harness
again, then /proxy restart.
An annotated example #
version: 1
harness:
default_model: gpt-6-sol # or an alias
auto_model: false # true: /model auto on from the start
auto_model_map: # pin what auto uses for each kind of work
heavy: gpt-6-sol
auto_avoid: ["*-codex*"] # the default; [] to allow them
effort: medium
compress_with_model: off # off (no summary request, no cost) | free | on
compress_model: gpt-6-sol-mini # with it on: who summarises; unset picks the cheapest suitable
compress_scope: same-account # same-account | same-provider | any
digest_key_points: on # quote decisions, fixes, open items from earlier replies; off to leave them out
permission:
mode: ask # ask | auto | yolo (yolo needs --yolo)
rules:
- { pattern: read_file, decision: allow }
- { pattern: "bash(rm -rf*)", decision: deny }
sandbox:
mode: auto # off | auto | strict
network: allow # allow | deny
when_unattended: off # on: contain commands in auto and yolo mode
file_policy:
read: hidden-only # hidden-only | project | anywhere
loop_guard: { mode: stop, warn_after: 3, stop_after: 6 }
tool_output: { failed_max_lines: 120 } # 0 = never shorten
lsp: auto # auto | off
bash_file_writes: warn # warn | deny | allow
ledger: "off" # off | auto
cost_preview: "off" # off | large | on (an estimate, never sent to the model)
subagents: { max_parallel: 3, max_turns: 50 }
notifications:
desktop: true
events: [approval, error, stalled]
retention: { sessions_days: 30, keep_per_dir: 5, auto_prune: false }
Read next: Commands and keys, Proxy settings, and Settings by goal.