Keep it running in the background #
On this page
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 statussays whether it runs, anduninstallremoves 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 installagain 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,
installsays so and writes nothing; useservice printand place the file yourself.
The step-by-step guides for each system follow.
What you get #
| Linux | macOS | |
|---|---|---|
| The file it writes | ~/.config/systemd/user/maple-proxy.service | ~/Library/LaunchAgents/com.kinncj.maple-proxy.plist |
| Starts | when you log in (at boot too, after one extra command below) | when you log in |
| If it stops with an error | restarted 3 seconds later | restarted 5 seconds later |
| Logs | journalctl --user -u maple-proxy | ~/.config/maple-harness/run/maple-proxy.log |
| Runs | maple-proxy serve --logs stdout | maple-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.
Install the programs.
curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash maple-proxy versionThis puts them in
/usr/local/binand asks forsudoonce. To avoidsudo, add-s -- --install-location ~/.local/binafterbashand make sure~/.local/binis on yourPATH.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
PATHthe service records:sudo apt install bubblewrapInstall the service.
maple-harness service install proxyIt prints where it wrote the file and whether the service is running:
proxy installed, active /home/you/.config/systemd/user/maple-proxy.serviceCheck 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/ # 200Then open
http://127.0.0.1:11539to sign in (Sign in).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"Over SSH. If
service installsays 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/busloginctl 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.
Install the programs.
curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash maple-proxy versionOptional: shell sandbox.
sudo pacman -S bubblewrapInstall the service.
maple-harness service install proxyCheck it.
maple-harness service status systemctl --user status maple-proxy journalctl --user -u maple-proxy -eStart 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.
Install the programs.
curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash maple-proxy versionOptional: shell sandbox.
sudo dnf install bubblewrapInstall the service.
maple-harness service install proxyCheck it.
maple-harness service status systemctl --user status maple-proxy journalctl --user -u maple-proxy -eStart at boot, not only at login.
loginctl enable-linger "$USER"SELinux. A user service that runs a program from
/usr/local/binor~/.local/binnormally 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.Firewall.
firewalldblocks 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.
Install the programs.
curl -fsSL https://raw.githubusercontent.com/kinncj/maple-harness-dist/main/install.sh | bash maple-proxy versionThe 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.Install the service. Run this in Terminal while you are logged in to the desktop:
maple-harness service install proxyIt writes
~/Library/LaunchAgents/com.kinncj.maple-proxy.plistand loads it into your login session.Check it.
maple-harness service status launchctl print gui/$(id -u)/com.kinncj.maple-proxy tail -f ~/.config/maple-harness/run/maple-proxy.logRestart it. Running
maple-harness service install proxyagain reloads it. So doeslaunchctl 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 installcreates. - 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, solaunchctlis 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.