Install #
On this page
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, andmaple-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 versionto 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 #
| System | Agent and proxy | Apple on-device model |
|---|---|---|
| macOS, Apple silicon | yes | yes (macOS 26 or newer) |
| macOS, Intel | yes | no |
| Linux, amd64 and arm64 | yes | no |
| Windows, amd64 | yes (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,.rpmand.apkpackages 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.
| System | Command |
|---|---|
| Arch, Manjaro | sudo pacman -S bubblewrap |
| Debian, Ubuntu | sudo apt install bubblewrap |
| Fedora, RHEL | sudo dnf install bubblewrap |
| openSUSE | sudo zypper install bubblewrap |
| Alpine | sudo apk add bubblewrap |
| macOS | nothing: 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.
| File | What it is |
|---|---|
maple-harness_linux_amd64, maple-harness_linux_arm64, maple-harness_darwin_arm64, maple-harness_darwin_amd64, maple-harness_windows_amd64.exe | The agent |
maple-proxy_linux_amd64, maple-proxy_linux_arm64, maple-proxy_darwin_arm64, maple-proxy_darwin_amd64, maple-proxy_windows_amd64.exe | The proxy |
maple-sidecar_darwin_arm64 | The Apple on-device model helper (Apple silicon only) |
maple-harness_windows_amd64.zip | From 2.0: the Windows agent and proxy in one zip, with the licence |
SHA256SUMS, SHA256SUMS.sig | The checksum of every file, and its signature |
LICENSE, THIRD_PARTY_NOTICES.md | The 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.