paperclip: systemd service, env file, and port firewall #62

New issue

Open

opened 2026-10-25 12:06:20 +00:00 by lab · 0 comments

lab commented

2026-10-25 12:06:20 +00:00

Owner

Context

Paperclip must survive reboots and stay reachable only from the LAN and
Tailscale, matching ct253.

Steps

/etc/systemd/system/paperclip.service, modeled on opencode.service:

[Unit]
Description=Paperclip Agent Orchestrator
After=network-online.target tailscaled.service
Wants=network-online.target

[Service]
User=paperclip
Group=paperclip
WorkingDirectory=/srv/paperclip
EnvironmentFile=/etc/paperclip/paperclip.env
ExecStart=/srv/paperclip/.local/bin/paperclipai run
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

/etc/paperclip/paperclip.env (0600, owned by paperclip):

HOST=0.0.0.0
PAPERCLIP_DEPLOYMENT_MODE=authenticated
PAPERCLIP_DEPLOYMENT_EXPOSURE=private
PAPERCLIP_AUTH_BASE_URL_MODE=auto

Run onboarding once as the paperclip user with --bind lan --yes --no-install-service, then paperclipai allowed-hostname 192.168.0.54.
nft table inet paperclip: accept tcp/3100 on eth0 and tailscale0,
drop the rest.
systemctl enable --now paperclip

Done when

systemctl is-active paperclip is active
curl http://192.168.0.54:3100/api/health returns {"status":"ok"}
the same works over the tailnet address
the port is closed on any other interface

Notes

Onboarding prints a /board-claim/<token> URL. Open it once as the board.
paperclipai service install is deliberately skipped: it needs user systemd
plus lingering, and the hand-written unit matches the repo pattern.

## Context Paperclip must survive reboots and stay reachable only from the LAN and Tailscale, matching `ct253`. ## Steps 1. `/etc/systemd/system/paperclip.service`, modeled on `opencode.service`: ```ini [Unit] Description=Paperclip Agent Orchestrator After=network-online.target tailscaled.service Wants=network-online.target [Service] User=paperclip Group=paperclip WorkingDirectory=/srv/paperclip EnvironmentFile=/etc/paperclip/paperclip.env ExecStart=/srv/paperclip/.local/bin/paperclipai run Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` 2. `/etc/paperclip/paperclip.env` (0600, owned by `paperclip`): ```text HOST=0.0.0.0 PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_DEPLOYMENT_EXPOSURE=private PAPERCLIP_AUTH_BASE_URL_MODE=auto ``` 3. Run onboarding once as the `paperclip` user with `--bind lan --yes --no-install-service`, then `paperclipai allowed-hostname 192.168.0.54`. 4. nft `table inet paperclip`: accept tcp/3100 on `eth0` and `tailscale0`, drop the rest. 5. `systemctl enable --now paperclip` ## Done when - `systemctl is-active paperclip` is `active` - `curl http://192.168.0.54:3100/api/health` returns `{"status":"ok"}` - the same works over the tailnet address - the port is closed on any other interface ## Notes - Onboarding prints a `/board-claim/<token>` URL. Open it once as the board. - `paperclipai service install` is deliberately skipped: it needs user systemd plus lingering, and the hand-written unit matches the repo pattern.