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.

Keep it running in the background #

On this page
  1. In plain words
  2. In short
  3. What you get
  4. Debian and Ubuntu
  5. Arch Linux
  6. Fedora
  7. macOS
  8. Keep the phone gateway running too
  9. Machines with no desktop
  10. Reach the setup page from another machine
  11. Update
  12. Troubleshooting
  13. Remove it
  14. Advanced: one system-wide service

By default the agent starts the proxy for you when you open it, and it stops when you are done. Run the proxy as a service when you want it to be already there: before you open a terminal, for other tools that use your models, or for your phone.

maple-harness service install does it in one command. It writes one small file for your own account (a systemd user service on Linux, a launchd agent on macOS) and starts it. Nothing runs as root, nothing is installed system-wide, and the file contains no key or token: those stay where they always are. Windows is not supported.

In plain words #

  • What it is. A way to keep the proxy (and the phone gateway) running in the background, started when you log in, instead of only while the agent is open.
  • Why you want it. Your phone, Claude Code or another tool can use your models without a Maple session open.
  • What to do. maple-harness service install, once. maple-harness service status says whether it runs, and uninstall removes it. It runs as you, never as root, and holds no key. There is no setup page step.

In short #

maple-harness service keeps the proxy and the phone gateway running in the background and starts them when you log in. On Linux it writes systemd user units; on macOS, launchd agents.

maple-harness service install            # the proxy and the gateway
maple-harness service install proxy      # one of them
maple-harness service status             # installed? running?
maple-harness service print gateway      # show what would be written; write nothing
maple-harness service uninstall          # stop and remove what install wrote

You do not need this to use the agent: it starts the proxy itself, and /remote starts the gateway. Install a service when you want the phone to work without a session open, or the proxy running before you open a terminal.

  • Logs. Linux: journalctl --user -u 'maple-*' -f. macOS: ~/.config/maple-harness/run/maple-<name>.log.
  • Start at boot, not at login (Linux). loginctl enable-linger "$USER".
  • After moving or reinstalling the programs, run service install again so the file points at the new path.
  • A file you edited is left alone unless you pass --force.
  • In a container or an SSH session with no user manager, install says so and writes nothing; use service print and place the file yourself.

The step-by-step guides for each system follow.

What you get #

LinuxmacOS
The file it writes~/.config/systemd/user/maple-proxy.service~/Library/LaunchAgents/com.kinncj.maple-proxy.plist
Startswhen you log in (at boot too, after one extra command below)when you log in
If it stops with an errorrestarted 3 seconds laterrestarted 5 seconds later
Logsjournalctl --user -u maple-proxy~/.config/maple-harness/run/maple-proxy.log
Runsmaple-proxy serve --logs stdoutmaple-proxy serve --logs stdout

The proxy still listens on the same addresses as always: the setup page on 127.0.0.1:11539, the OpenAI-compatible API on 127.0.0.1:11535 and the Anthropic-compatible API on 127.0.0.1:11537. See The proxy. The setup page only ever listens on the machine itself.

The service file records two things from the shell where you ran install: the full path to the program, and your PATH (and XDG_CONFIG_HOME, if you set it). So run install from a normal terminal where maple-proxy works, and run it again if you move the programs or change your PATH.

Debian and Ubuntu #

Tested on: written from how the command works and standard systemd behaviour; not yet run on Debian or Ubuntu.

  1. Install the programs.

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

    This puts them in /usr/local/bin and asks for sudo once. To avoid sudo, add -s -- --install-location ~/.local/bin after bash and make sure ~/.local/bin is on your PATH.

  2. Optional: shell sandbox. Sessions you share with your phone contain their shell commands with bubblewrap when it is installed. Install it before the next step so it is on the PATH the service records:

    sudo apt install bubblewrap
  3. Install the service.

    maple-harness service install proxy

    It prints where it wrote the file and whether the service is running:

    proxy    installed, active
             /home/you/.config/systemd/user/maple-proxy.service
  4. Check it.

    maple-harness service status
    systemctl --user status maple-proxy
    curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:11539/    # 200

    Then open http://127.0.0.1:11539 to sign in (Sign in).

  5. Start at boot, not only at login. A user service normally stops when you log out. On a machine that should keep serving, turn on lingering, which keeps your user services running without a login session:

    loginctl enable-linger "$USER"
  6. Over SSH. If service install says the systemd user manager is not reachable, install the user bus (sudo apt install dbus-user-session), log in again, and if needed point the tools at your session:

    export XDG_RUNTIME_DIR=/run/user/$(id -u)
    export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus

    loginctl enable-linger "$USER" (step 5) makes that session exist even when nobody is logged in.

If the machine runs ufw and you also keep the phone gateway running, allow its port from Tailscale only: sudo ufw allow in on tailscale0 to any port 11541 proto tcp. The proxy's own ports need no firewall rule, because they listen on this machine only.

Arch Linux #

Tested on: Arch Linux. The service files it writes pass systemd-analyze verify. The install and enable steps themselves have not been run on a real machine yet.

  1. Install the programs.

    curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash
    maple-proxy version
  2. Optional: shell sandbox.

    sudo pacman -S bubblewrap
  3. Install the service.

    maple-harness service install proxy
  4. Check it.

    maple-harness service status
    systemctl --user status maple-proxy
    journalctl --user -u maple-proxy -e
  5. Start at boot, not only at login.

    loginctl enable-linger "$USER"

Arch has no firewall enabled by default. If you added one and want the phone gateway reachable over Tailscale, allow port 11541 on the tailscale0 interface only.

Fedora #

Tested on: written from how the command works and standard systemd behaviour; not yet run on Fedora.

  1. Install the programs.

    curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash
    maple-proxy version
  2. Optional: shell sandbox.

    sudo dnf install bubblewrap
  3. Install the service.

    maple-harness service install proxy
  4. Check it.

    maple-harness service status
    systemctl --user status maple-proxy
    journalctl --user -u maple-proxy -e
  5. Start at boot, not only at login.

    loginctl enable-linger "$USER"
  6. SELinux. A user service that runs a program from /usr/local/bin or ~/.local/bin normally works with the default policy. If the service fails to start with a "permission denied" that you cannot explain, look for a denial: sudo ausearch -m avc -ts recent.

  7. Firewall. firewalld blocks incoming connections on most Fedora editions. The proxy's own ports listen on this machine only, so they need no rule. If you keep the phone gateway running, allow it from Tailscale only: sudo firewall-cmd --permanent --zone=trusted --add-interface=tailscale0 && sudo firewall-cmd --reload.

macOS #

Tested on: written from how the command works and standard launchd behaviour; not yet run on a Mac.

  1. Install the programs.

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

    The programs are not notarised by Apple. The installer downloads them with curl, which normally does not trigger Gatekeeper. If macOS still refuses to open one, remove the quarantine mark from it: xattr -d com.apple.quarantine /usr/local/bin/maple-proxy.

  2. Install the service. Run this in Terminal while you are logged in to the desktop:

    maple-harness service install proxy

    It writes ~/Library/LaunchAgents/com.kinncj.maple-proxy.plist and loads it into your login session.

  3. Check it.

    maple-harness service status
    launchctl print gui/$(id -u)/com.kinncj.maple-proxy
    tail -f ~/.config/maple-harness/run/maple-proxy.log
  4. Restart it. Running maple-harness service install proxy again reloads it. So does launchctl kickstart -k gui/$(id -u)/com.kinncj.maple-proxy.

Things that are specific to the Mac:

  • It runs while you are logged in. A launchd agent belongs to your login session, so it starts when you log in and stops when you log out. A Mac that must serve with nobody logged in needs automatic login; a system-wide launchd daemon is not something service install creates.
  • The Apple on-device model helper is started by the proxy itself. It is not a separate service and needs nothing from you.
  • Your keys are in the login Keychain, which is unlocked while you are logged in. If macOS asks whether the proxy may use the Keychain, choose to allow it.
  • The command must run from a desktop login. Over SSH without a desktop session the gui/<uid> domain does not exist, so launchctl is likely to refuse to load the agent.

Keep the phone gateway running too #

The gateway is the address your phone connects to (Control it from your phone). To keep it up as well:

maple-harness service install gateway      # or: maple-harness service install     (both)

This also switches remote control on and starts the gateway listening on your network (port 11541) with HTTPS: a real certificate when Tailscale is signed in, otherwise a self-signed one that works after a browser warning but cannot send notifications while the page is closed. No secret is put in the service file. Afterwards:

maple-harness gateway pair                     # a single-use code and a QR code for your phone
maple-harness gateway workspaces add ~/code    # folders a phone may start sessions in

The gateway service refuses to start until remote control is on and there is a way for a device to sign in; while that is missing it restarts and fails quietly. service install gateway switches remote control on, and gateway pair gives a device something to sign in with. If you set up Tailscale later, run maple-harness service install gateway again to switch it to the trusted certificate.

The gateway keeps running until you stop it. One that a session starts with /remote stops by itself after ten idle minutes; the service does not.

Machines with no desktop #

Your sign-ins and keys go in the system keyring when there is one, and the configuration file holds only a reference to them. A server usually has no keyring: no Secret Service is running on your user session, or it cannot be unlocked without someone at the keyboard. Then the proxy falls back to a private file in the configuration folder (readable only by you) and tells you so. To see where things are stored, without showing the secrets:

maple-proxy secrets status

The output says file or operating-system keyring and lists where each secret lives. The file is protected by your account's permissions and your disk, so on a shared machine keep the account private and consider encrypting the disk. Run the command from the same account and environment the service uses, so both look at the same configuration folder.

Reach the setup page from another machine #

The setup page listens on 127.0.0.1 only and refuses to listen anywhere else, so do not try to expose it. To use it on a server, forward the port over SSH and open it in your own browser:

ssh -L 11539:127.0.0.1:11539 you@server

Then browse to http://127.0.0.1:11539 on your own machine. Over Tailscale the same forward works with the machine's Tailscale name. To let other machines use the model APIs (not the setup page), see Using it from another machine.

Update #

Each program updates itself, then the service needs a restart to run the new copy:

maple-harness update
maple-proxy update
systemctl --user restart maple-proxy maple-gateway     # Linux
maple-harness service install                          # macOS: reloads the agents

If update says permission denied for /usr/local/bin, run it with sudo, or install into ~/.local/bin the first time. If you moved the programs, run maple-harness service install again so the file points at the new path.

Troubleshooting #

service install says the systemd user manager is not reachable. There is no user session to attach to, typically over SSH or in a container. Log in through a normal session, or follow the SSH steps in the Debian and Ubuntu section. maple-harness service print proxy shows the file it would write so you can place it yourself.

The service is installed but not running. Read why it stopped:

systemctl --user status maple-proxy
journalctl --user -u maple-proxy -e          # on macOS: tail ~/.config/maple-harness/run/maple-proxy.log

The port is already in use (11535, 11537 or 11539). Something else, often a proxy you started by hand, holds it. Find it with ss -ltnp | grep -E ':1153[579]' on Linux or lsof -nP -iTCP:11539 -sTCP:LISTEN on a Mac, stop it, then restart the service. You can also change the addresses under server: in config.yaml.

It works in a terminal but not as a service. The service uses the PATH and XDG_CONFIG_HOME from the moment you ran install. Run maple-harness service install again from a shell where the tools you want are on the PATH.

My sign-ins are missing under the service. The service is reading a different configuration folder than your terminal. Compare maple-proxy secrets status in your terminal with the folder the service uses (the XDG_CONFIG_HOME line in its file); both should be the same.

install leaves a file alone. It will not replace a file you edited or wrote yourself. Add --force to replace it.

The gateway keeps restarting. Remote control is off, or nothing can sign in yet. See Keep the phone gateway running too.

maple-harness doctor also checks the proxy and the gateway and says how to fix what it finds.

Remove it #

maple-harness service uninstall

This stops the services and removes the files it wrote. It leaves your configuration and sign-ins alone. On Linux, if you turned lingering on and no longer want it: loginctl disable-linger "$USER".

Advanced: one system-wide service #

Tested on: the unit text was checked with systemd-analyze verify on Arch Linux. Nothing else here has been run. Use the per-user service above unless you need this.

A per-user service is the right default. If you want the proxy to run under its own account, for example on a server that nobody logs in to, you can write a system service yourself. This runs the proxy only.

Create the account and install the programs where that account can run them (/usr/local/bin is where the installer puts them; a copy in a home folder will not work with the settings below):

sudo useradd --system --home-dir /var/lib/maple --no-create-home --shell /usr/sbin/nologin maple

Then create /etc/systemd/system/maple-proxy.service:

[Unit]
Description=Maple Harness proxy (system service)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=maple
Group=maple
ExecStart=/usr/local/bin/maple-proxy serve --logs stdout
Environment=HOME=/var/lib/maple
WorkingDirectory=/var/lib/maple
StateDirectory=maple
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
LockPersonality=true

[Install]
WantedBy=multi-user.target

Start it, and follow the log:

sudo systemctl daemon-reload
sudo systemctl enable --now maple-proxy
sudo journalctl -u maple-proxy -f

StateDirectory=maple creates /var/lib/maple, owned by the maple account and the only place the service may write (ProtectSystem=strict makes everything else read-only). Its configuration and sign-ins live in /var/lib/maple/.config/maple-harness. Sign in through the setup page with the SSH forward described above, and check where secrets are kept with sudo -u maple -H maple-proxy secrets status. There is no keyring for a system account, so they will be in the private file.

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