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.

Your first session #

On this page
  1. In plain words
  2. 1. Start the proxy
  3. 2. Sign in or add a model
  4. 3. Start the agent
  5. Where things are kept
  6. Next

A first session in three steps.

In plain words #

  • Three steps: start the proxy (or let the agent start it), sign in to an account or add a model server on the setup page, then run maple-harness in your project.
  • The clicks. Open http://127.0.0.1:11539. On a first run the Overview shows Get started: sign in to Anthropic or GitHub Copilot there, or add a model server under Providers. Then go to your project and type.

1. Start the proxy #

maple-proxy serve

The proxy is the one program that talks to models and keeps your sign-ins. The agent starts it for you if nothing is listening, so you can skip this step, but running it yourself lets you watch what it does. On first run it looks for Ollama and Apple's on-device model and writes a working starter configuration.

It opens three local addresses:

AddressWhat it is
http://127.0.0.1:11539The setup page: sign in, add models, make access tokens
http://127.0.0.1:11535/v1An OpenAI-compatible API for your models
http://127.0.0.1:11537An Anthropic-compatible API for your models

2. Sign in or add a model #

Open http://127.0.0.1:11539 and either sign in to GitHub Copilot, save an Anthropic API key, or add a local model server. If a model server is already running on this computer, the page offers to add it (see Find the servers already running). Or do it from the terminal:

maple-harness auth login github-copilot
maple-harness auth login claude

Details for each are in Sign in and Connect a model server.

3. Start the agent #

Go to a project directory and run:

maple-harness
The start screen: a pixel-art beaver next to the name and version, a tip, the message box for the acme-api project and the status barThe start screen: a pixel-art beaver next to the name and version, a tip, the message box for the acme-api project and the status bar
The start screen in a project called acme-api. Type in the box at the bottom; /help lists every command.

Type what you want done. Useful first commands:

CommandWhat it does
/modelChoose a model from the list, or /model auto to let the agent choose per message
/helpList every command
/remoteShare this session with your phone (Control it from your phone)
/sandboxSee whether shell commands are contained
/lspSee which language servers are in use, so the agent sees compile errors after each edit (Language servers)
/clearStart over

By default the agent asks before it writes a file or runs a command. Answer with the keys shown. Rules in your configuration can allow or deny specific tools; a deny rule always wins. The flag --yolo allows everything you would otherwise be asked about (deny rules still apply), so use it only in a throwaway checkout or a container.

If something does not work, run maple-harness doctor. It checks the install and says how to fix each problem.

Where things are kept #

Everything lives in ~/.config/maple-harness/ (%APPDATA%\maple-harness on Windows): the configuration file config.yaml, saved sessions, memory notes, and your sign-ins. Sign-ins are kept in your system keyring where there is one, not in the configuration file.

Next #

Every command, key and setting, with what it does and its trade-off: Commands and keys, Harness settings and the Proxy settings. For the setting that fits a goal, see Settings by goal.

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