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.

Glossary #

The words these pages use, in alphabetical order, each with the page that covers it.

Access token. A secret that lets a device or another machine use what runs on this one: a paired phone driving or watching sessions, or another machine using the proxy's model APIs. Each token carries only what it is for, and you can revoke it at any time. See Control it from your phone and Using it from another machine.

Account. One sign-in with a provider: a GitHub Copilot seat or an Anthropic API key. You can add more than one of the same provider, each with its own name, and the proxy can move to the next account when one cannot answer. See Sign in.

Agent. maple-harness (also mpl on macOS and Linux), the program you work with in a terminal. It reads your project, edits files and runs commands for you, and by default asks before it writes a file or runs a command. It starts the proxy if nothing is listening. See Your first session.

AI units. What GitHub Copilot charges per request, as Copilot reports it on each response. /cost, the setup page's Cache card and the usage log show them, and daily budgets can cap them. Anthropic's API reports tokens only. See What /cost tells you.

Alias. A short, fixed name for a model, such as local or cloud, that you can point at a different model later without changing the tools that use it. Set in model_aliases, or as a model's own alias. See Proxy settings.

Efficient, efficacious, effective. The three goals every setting is tagged with in the reference pages. 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. See Settings by goal.

Fallback. What the proxy tries when a model cannot answer because its account is out of quota or credit, the backend is overloaded, or it is unreachable. model_fallbacks lists other models to try; provider_fallbacks lists other accounts. It happens only before any output is sent, and only if you add a rule. See Fallbacks.

Gateway. The one address on your computer that phones and other computers connect to for remote control, on port 11541 by default. /remote starts it and it stops by itself after ten idle minutes; maple-harness gateway start or a background service keeps it running. See Control it from your phone and Keep it running in the background.

MCP. The Model Context Protocol, a common way for tools to offer a model extra tools. The agent can use MCP servers you configure, and maple-harness mcp serve offers this project's notes and code map to other tools. See Give other tools this project's knowledge.

Modes: ask, auto and yolo. What happens when the model wants to write a file or run a command. ask, the default, asks you each time. auto and yolo both let it go ahead without asking; yolo exists only when you start with --yolo, so a configuration file can never turn it on by itself. deny rules apply in every mode. Shift+Tab cycles them. See Commands and keys.

Pairing. How a phone or another computer gets its own access token: /remote pair or maple-harness gateway pair shows a short code and a QR code that work once and expire in five minutes. See Control it from your phone.

Provider. A place models come from, as the proxy knows it: GitHub Copilot, Anthropic, or a model server such as Ollama or LM Studio. Each has an id in config.yaml, and <provider id>/<model> names one provider's copy of a model. See Connect a model server and Sign in.

Proxy. maple-proxy (also mplp on macOS and Linux), the program that holds your sign-ins and talks to the models. The agent uses it, and so can any tool that speaks the OpenAI API (port 11535) or the Anthropic API (port 11537). See The proxy and its setup page.

Remote page. The web page a paired phone or browser opens from the gateway: it lists your shared sessions, shows each one as it runs, lets you send messages and approve tool calls, and starts sessions in folders you have allowed. See Control it from your phone.

RPC. maple-harness --rpc, which lets another program drive a session with one JSON object per line on standard input and output, for a CI step, an editor plugin or a script. See Drive it from another program.

Sandbox. A limit on the commands the model runs in the shell: they can write only in your project and a few build caches, cannot see your logins and keys, and run with secret-looking variables removed. Built in on macOS, bubblewrap on Linux, not available on Windows. See The shell sandbox.

Setup page. The proxy's web page at http://127.0.0.1:11539, reachable from this computer only. Sign in, add model servers, change the proxy's settings, manage remote access and see what was spent. It can have a password. See The proxy and its setup page.

Share. A link to one session: the person who opens it can watch that session live until the share ends (1 hour to 7 days; 24 hours unless you choose), and cannot see anything else. A share made with Can drive this session (8 hours unless you choose) also lets them send messages and answer approvals in that session. The link works once, for the first person to open it within 10 minutes. A share follows its conversation, not the conversation's name. See Sharing one session.

Subagent. A second session that the agent hands a small, self-contained job to, such as a search or a review. It has its own instructions, tools and optionally its own model, and only its final report comes back, so the main conversation stays small. See Subagents.

Usage log. A file the proxy writes with one line of counts per request (model, tokens, cache figures, AI units, timing), never prompts or answers. It is on by default, one file per UTC day in the usage folder of the Maple Harness config folder, and daily files older than 90 days are deleted. See Your usage data.