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.

Harness settings #

On this page
  1. In plain words
  2. Settings at a glance
  3. Per-project overrides
  4. Model choice
  5. Long conversations
  6. Permissions and safety
  7. Runaways and long output
  8. Cost preview
  9. Language servers and shell writes
  10. Tools, skills and hooks
  11. Subagents and remote control
  12. Notifications
  13. Housekeeping and appearance
  14. Where the harness finds the proxy
  15. 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.yaml under harness:.
  • What to do. Most people never edit it: /settings in 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 #

KeyDefaultHelps
default_modelnoneEffective
compress_with_modeloffEfficient
compress_model, compress_scopenone (chosen for you), same-accountEfficient, Efficacious
digest_key_pointsonEffective
auto_model, auto_model_map, auto_avoid, auto_model_resolution, auto_first_weightoff, none, *-codex*, client, heavyEfficient, Effective
fusion_turn_budgetnoneEfficient
effort, disable_thinkingnone, offEfficient
permission.mode, permission.rules[]ask, shipped rulesEfficacious
sandbox.*off locally, auto while sharedEfficacious
file_policy.*onEfficacious
loop_guard.mode, loop_guard.warn_after, loop_guard.stop_afterstop, 3, 6Efficient, Effective
tool_output.failed_max_lines120Efficient
disable_auto_continueoffEffective
max_auto_continues50Efficient, Effective
ledgeroffEffective
cost_preview, cost_preview_large_tokens, cost_preview_confirm_aboveoff, 50000, unsetEffective
lsp, lsp_servers[]auto, noneEffective, Efficacious
bash_file_writeswarnEfficacious
subagents.max_parallel, subagents.max_turns3, 50Efficient, Effective
delegates.claude_code and its delegates.claude_code_* settingsoffEffective, Efficacious
notifications.*offEffective
remote.allow_yolooffEfficacious
retention.*30, 5, offEfficient
proxy_logsoffEffective
first_output_timeout_secondsfollow the proxy (10 minutes, or longer for a slow local model)Effective
proxy.url, proxy.token, proxy.allow_insecure, proxy.trust_uncheckednone (the proxy on this machine), offEffective, 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 #

KeyDefaultWhat it doesTrade-offHelps
default_modelnoneThe 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 proxyEffective
auto_modeloffStart with /model auto on: a model chosen for each message from what your provider serves, keeping your model when it fitsChoosing a model has a bill attached, so it is opt-inEfficient, Effective
fusion_turn_budgetnoneAI 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 modelA hard turn can finish on a cheaper tier, with no reviewEfficient
auto_model_mapnonePin 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 noteYou take over the rankingEffective
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 blockedA pattern may hide a model you would have likedEffective
auto_first_weightheavyWhere auto starts a new message, before any work is under way: heavy or medium. Planning and questions that ask for judgement stay heavyMedium is cheaper per request, but a hard task on a weaker model can cost the work; compare with maple-harness bench firstEfficient
auto_model_resolutionclientclient 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 thereThe 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 thisEfficient, Effective
effortnoneStart with a reasoning-effort level the model acceptsHigher effort thinks longer and costs moreEfficient, Effective
disable_thinkingoffStart with thinking offFaster and cheaper, at the price of harder problemsEfficient
compress_with_modeloffWhether 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 toofree and on send the earlier conversation to the summarising model; on can spend creditEfficient
compress_modelnoneWith 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_scopeA model you name is used even when a cheaper one would do, and even outside compress_scope, with a noteEfficient, Effective
compress_scopesame-accountWhere 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 anyWidening it can send your conversation to a service or account you did not pick for itEfficacious
digest_key_pointsonWhether 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 outIt 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 requestsEffective

Long conversations #

When a conversation outgrows the model's window, older messages leave the model's view. What leaves it is kept and searchable:

  1. 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_search tool: 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: --continue and --resume bring it back, a /fork or /clone gets its own copy, and removing the session removes it. It stays on your machine with the same file permissions as the session.
  2. 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 that history_search finds them.
  3. 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.
  4. A written summary, only if you ask for one with compress_with_model. With free, only a model on your own machine or network is asked. With on, 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 within compress_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; Esc stops it and leaves the conversation as it was. /cost lists 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 #

KeyDefaultWhat it doesTrade-offHelps
permission.modeaskThe starting mode: ask, auto or yolo. yolo is honoured only when you start with --yoloEfficacious
permission.rules[].pattern, permission.rules[].decisionshipped rulesRules 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 lessEfficacious
sandbox.modeunset: off for a normal session, auto while a session is sharedContains 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 nothingContained commands see fewer files and, while shared, no networkEfficacious
sandbox.networkunset: allowed locally, denied while shareddeny cuts the network for contained commands; allow keeps it (installs and downloads then work)Denying it breaks npm install and git cloneEfficacious
sandbox.extra_writable, sandbox.extra_readonly, sandbox.hidenoneMore paths the sandbox may write, may read, or hides (absolute, ~/…, or relative to the project)Efficacious
sandbox.env_allownoneEnvironment variables that survive the scrubbing of secret-looking onesEach one you allow is visible to contained commandsEfficacious
sandbox.when_unattendedoffon: 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 sandboxContained commands cannot use hidden logins (git over SSH, gh, cloud tools, Docker) until you allow themEfficacious
file_policy.modeonConfines the file tools. off removes the confinementEfficacious
file_policy.readhidden-onlyhidden-only: read anywhere except places that hold credentials. project: only the project, the temp directory and extra_readable. anywhere: no limit, which is not safeproject blocks reading outside the projectEfficacious
file_policy.hide, file_policy.extra_writable, file_policy.extra_readablenoneMore places to hide; more places writes may go besides the project and the temp directory; more places reads may go under read: projectEfficacious
bash_file_writeswarnWhat 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 nothingThe file tools show you a diff and run safety checks; a shell write does notEfficacious

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 #

KeyDefaultWhat it doesTrade-offHelps
loop_guard.modestopWhat 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 oneEfficient, Effective
loop_guard.warn_after3How many similar failures before the noteLower nags soonerEffective
loop_guard.stop_after6How many similar failures before the turn ends and asks for your guidanceLower stops soonerEfficient
tool_output.failed_max_lines120How 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 shortenedThe model sees less of a long log, and can read the saved file if it needs the restEfficient
disable_auto_continueoffStops 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 checkTurning it off means you type "continue" yourselfEffective
max_auto_continues50The 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 1000Lower stops a model that keeps narrating sooner, and a long task may need you to type "continue"Efficient
ledgeroffauto 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 /ledgerOne extra model call for such requestsEffective

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.

KeyDefaultWhat it doesTrade-offHelps
cost_previewoffBefore 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 messageOne small read-only question to your proxy before each message it coversEffective
cost_preview_large_tokens50000How large a request must be, in tokens, before large shows its estimateLower shows it more oftenEffective
cost_preview_confirm_aboveunsetAsks 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 saysA --prompt run with no one to answer does not send such a message, and exits with status 1Effective

How the figure is made and how to read it are in What /cost tells you.

Language servers and shell writes #

KeyDefaultWhat it doesTrade-offHelps
lspautoWith 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 offThe first edit starts the server in the background, and a timeout adds nothingEffective, Efficacious
lsp_servers[].extensions, lsp_servers[].command, lsp_servers[].argsnoneName a server yourself, for example {extensions: [".go"], command: gopls}. When any are set, nothing is detectedYou maintain the listEffective

The table of languages, marker files and install commands is in Language servers.

Tools, skills and hooks #

KeyDefaultWhat it doesHelps
mcp_servers[].namerequiredThe 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_servers[].typeinferredhttp or sse for a remote server. A command means a local oneEffective
mcp_servers[].command, mcp_servers[].args, mcp_servers[].envnoneA local (stdio) server: the program, its arguments and extra environmentEffective
mcp_servers[].url, mcp_servers[].headersnoneA remote server and the headers sent with every request (values may be ${env:NAME} or ${secret:name})Effective
mcp_servers[].allow_insecure, mcp_servers[].allow_privateoffPermit 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 themEfficacious
skills.sources[].path, skills.sources[].ecosystem.claude/ in the project and your homeWhere to load skills from, and the convention each directory follows (claude, opencode or npx)Effective
hooks.filesdiscoveredHook files to load. Empty means the default places; hooks run shell commands, so treat a hooks file like a scriptEffective
graph.pathper project, under the config directoryWhere 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 #

KeyDefaultWhat it doesTrade-offHelps
subagents.max_parallel3How many subagents run at once (1 to 16). More wait for a free slotA local model may not serve several at onceEfficient, Effective
subagents.max_turns50The most turns any one subagent may take, whatever its own limit asks for (1 to 200)Efficient
delegates.claude_codeoffon lets a session hand a whole task to your own installed, signed-in Claude Code, on this machine. See Delegate to your local ClaudeIt uses your Claude plan and its limitsEffective
delegates.claude_code_accessreadWhat 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 itMore access, less you see before it actsEfficacious
delegates.claude_code_project_settingsoffon 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 askingEfficacious
delegates.claude_code_max_turns20The most turns one run may take (1 to 200)Efficient
delegates.claude_code_timeout_minutes15How long one run may take before it is stopped (1 to 240)Efficient
delegates.claude_code_pathemptyThe 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 runsEfficacious
delegates.claude_code_optionsnoneExtra 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 folderEffective
remote.allow_yolooffLets 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 runEvery approval is skipped for that sessionEfficacious

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.

KeyDefaultWhat it doesHelps
notifications.desktopoffA notification on this machineEffective
notifications.sinks[].typerequiredntfy, webhook, command, desktop or bellEffective
notifications.sinks[].namenoneA label for the destination
notifications.sinks[].url, notifications.sinks[].token, notifications.sinks[].headersnoneWhere to send it, and any credentials. Write them as ${env:NAME} or ${secret:name}Efficacious
notifications.sinks[].insecure_httpoffAllow plain http to a host that is not this machineEfficacious
notifications.sinks[].command, notifications.sinks[].argsnoneA program to run, never through a shell. Arguments may hold {title}, {body}, {kind}, {session} and {url}Effective
notifications.eventsapproval, error, stalled, alert and deviceWhich 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 forEffective
notifications.approval_delay20sHow long a question stays open before it is worth a message, so answering at the keyboard sends nothingEffective
notifications.min_turn60sHow long a turn must run before done is sentEffective
notifications.include_tooloffAdd the tool's name to an approval message. Arguments are never includedEfficacious
notifications.max_per_minute6The most messages in total per minuteEfficacious
notifications.linknoneThe address a tap on the message opensEffective
notifications.web_pushonWhether the gateway may push to paired phones that turned notifications on in the web app. Nothing is sent until a phone subscribesEffective
notifications.push_subjectthe project's pageThe contact that push services see

Housekeeping and appearance #

KeyDefaultWhat it doesHelps
retention.sessions_days30How old a saved session must be before cleanup treats it as oldEfficient
retention.keep_per_dir5How many recent sessions per directory cleanup always keepsEfficient
retention.auto_pruneoffRun what cleanup --yes would, once a day, when a session startsEfficient
theme, theme_colorsthe default themeA colour theme by name, and per-role colour overrides
mouseonThe 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
animationsonHow 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_pasteautoCtrl+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_paste_commandnoneA 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_promptnoneText added to the harness's base instructionsEffective
engineering_prompt_modeautoWhether a short engineering-standards note is added: auto (only when the project has no AGENTS.md or CLAUDE.md), always or neverEfficacious
engineering_promptbuilt inReplaces the text of that noteEfficacious

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 (whatever omarchy theme current reports), 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_colors still applies on top. Choosing another theme with /theme <name> stops following until you choose /theme auto again. Everywhere else, including a Linux machine not running Omarchy, macOS or Windows, auto is maple.

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 #

KeyDefaultWhat it does
version1The configuration file's format version
server.openai_compat127.0.0.1:11535The proxy's OpenAI-compatible address, which the harness talks to
server.anthropic_compat127.0.0.1:11537The proxy's Anthropic-compatible address
server.webui127.0.0.1:11539The 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.

KeyDefaultWhat it does
proxy.urlnoneThe 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.tokennoneThat 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.allow_insecureoffAllows 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.trust_uncheckedoffWhile 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:

KeyDefaultWhat it does
first_output_timeout_seconds0: follow the proxyHow 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:

KeyDefaultWhat it does
proxy_logsoffWhere 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.

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