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.

Install #

On this page
  1. In plain words
  2. One line
  3. Platforms
  4. Optional: contain the shell (bubblewrap)
  5. Release files
  6. Update
  7. Uninstall
  8. Next

On every system Maple Harness is two programs: maple-harness, the agent, and maple-proxy, the proxy, which holds your sign-ins and talks to the models. On macOS and Linux the installer also adds the short names mpl and mplp. On a Mac with Apple silicon there is a third program, maple-sidecar, a small helper for Apple's on-device model; the proxy starts it when it is needed. The installer fetches what your system needs.

In plain words #

  • What it is. One command puts the two programs on your computer: maple-harness, the agent you talk to, and maple-proxy, which holds your sign-ins and talks to the models.
  • Why this way. It needs no account, it checks every file it downloads against the release's checksums, and it refuses anything that does not match.
  • What to do. Paste the line for your system into a terminal, then run maple-harness version to check. There is no setup page step: the proxy's page comes after, in Your first session.

One line #

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.ps1 | iex

No account or token is needed. The installer detects your system, downloads the release, checks every file against the release's SHA256SUMS, and refuses to install anything that does not match. To read it first, open it on GitHub.

On macOS and Linux it installs to /usr/local/bin by default, and asks for sudo only if it cannot write there. On Windows it installs to %LOCALAPPDATA%\Programs\MapleHarness for your account only, and offers to add that folder to your user PATH. To choose another place, or a specific release:

curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash -s -- --install-location ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | MAPLEHARNESS_VERSION=v2.6.2 bash

Check it worked:

maple-harness version
maple-proxy version

Platforms #

SystemAgent and proxyApple on-device model
macOS, Apple siliconyesyes (macOS 26 or newer)
macOS, Intelyesno
Linux, amd64 and arm64yesno
Windows, amd64yes (less tested)no
  • macOS. The shell sandbox is built in: nothing to install. The on-device model needs a Mac with Apple silicon and macOS 26 or newer; the agent and the proxy do not need it.
  • Linux. amd64 and arm64. Besides the one-line installer, stable releases carry .deb, .rpm and .apk packages for both. The shell sandbox needs bubblewrap (below).
  • Windows. amd64 only; on Windows on Arm the amd64 build runs under emulation. There is no shell sandbox on Windows, running the proxy as a background service is not supported, and it is less tested than macOS and Linux.

Optional: contain the shell (bubblewrap) #

The agent can run the commands its shell tool executes inside a sandbox. On macOS that is built in. On Linux it needs bubblewrap, which is optional: without it the shell still works, uncontained.

SystemCommand
Arch, Manjarosudo pacman -S bubblewrap
Debian, Ubuntusudo apt install bubblewrap
Fedora, RHELsudo dnf install bubblewrap
openSUSEsudo zypper install bubblewrap
Alpinesudo apk add bubblewrap
macOSnothing: built in

Only the Arch command has been run on a real machine here; the others are each system's usual package command.

Run /sandbox inside the agent, or maple-harness doctor, to see whether it works on your machine. What the sandbox does, what it breaks and how to turn it on are in The shell sandbox.

With the network allowed, contained commands still cannot connect to the proxy's setup page, so a command cannot change your settings or read your keys through it. They can reach everything else as before: the proxy's model addresses, your own local servers and the internet. On Linux this needs version 6.7 or later; on an older kernel commands run as before. /sandbox shows whether the setup page is blocked on your machine. The rule is by port, so a service on another computer that uses the setup page's port (11539 unless you changed server.webui) cannot be reached from a contained command either. Contained commands also cannot use Multipath TCP while the page is blocked: curl --mptcp fails as it would on a system with Multipath TCP switched off, and plain curl works.

Release files #

Each release on the releases page has these files. The installer picks the right ones; you only need this list to download by hand.

FileWhat it is
maple-harness_linux_amd64, maple-harness_linux_arm64, maple-harness_darwin_arm64, maple-harness_darwin_amd64, maple-harness_windows_amd64.exeThe agent
maple-proxy_linux_amd64, maple-proxy_linux_arm64, maple-proxy_darwin_arm64, maple-proxy_darwin_amd64, maple-proxy_windows_amd64.exeThe proxy
maple-sidecar_darwin_arm64The Apple on-device model helper (Apple silicon only)
maple-harness_windows_amd64.zipFrom 2.0: the Windows agent and proxy in one zip, with the licence
SHA256SUMS, SHA256SUMS.sigThe checksum of every file, and its signature
LICENSE, THIRD_PARTY_NOTICES.mdThe licence, and the licences of the code it includes

darwin is macOS. Check a file you downloaded by hand with sha256sum -c SHA256SUMS --ignore-missing (on macOS, shasum -a 256 -c SHA256SUMS --ignore-missing). macOS binaries are not notarised yet, so a download made by hand may need a right-click and Open the first time; the installer avoids this.

Update #

maple-harness update --check     # is there a newer release?
maple-harness update             # install it
maple-proxy update               # the proxy updates itself the same way

Uninstall #

rm -f /usr/local/bin/maple-{harness,proxy,sidecar} /usr/local/bin/{mpl,mplp}
rm -rf ~/.config/maple-harness     # your config, sign-ins, notes and saved sessions

The second line deletes your configuration, stored sign-ins, memory notes and saved sessions. Skip it if you plan to reinstall.

Next #

Your first session.

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