Linux server

Run Patterm as a systemd user service on a Linux machine, so your agents keep working when no window or browser is open.

The service is the same Patterm you get from the desktop app, without a window. You open it from a browser, either on the same machine or from another device (see Browser and phone access).

Requirements##

• Linux on x64 or arm64, with systemd and user services.
• Patterm installed with the release installer (see Installation). The release bundles its own Node, so you do not need to install Node.
• The agent CLIs you want to use, installed and signed in on the server, under the same account that runs the service.

Patterm runs agents with your user account's permissions. Run the service under the account that owns your repositories and CLI logins.

Start the service##

patterm --headless

The first time you run this, Patterm writes the service files and starts patterm.service. Later runs start the same service and do not restart it or interrupt its agents. Open http://localhost:8787 on that machine.

A new service accepts connections from the machine it runs on only. To open it from your phone or laptop, change Open from in Settings › Remote access. See Browser and phone access.

patterm --headless does not start the service at login or after a reboot. To do that, enable the unit and turn on lingering, which keeps your user services running after you log out:

systemctl --user enable patterm.service
sudo loginctl enable-linger "$USER"

Check on it##

systemctl --user status patterm.service
journalctl --user -u patterm.service -f
curl --fail http://127.0.0.1:8787/health

Startup and shutdown messages go to the journal. /health reports whether the service is ready, including whether its terminal engine is available. Use your own port in the URL if you changed PATTERM_PORT.

If the terminal engine exits, the service stops itself and systemd starts it again. Your agents are not affected, because they run in separate terminal host units (see below).

Where things live##

Patterm follows XDG_CONFIG_HOME and XDG_DATA_HOME when they are set. Set PATTERM_HOME before installing to put the installed versions somewhere other than ~/.local/share/patterm.

The data directory must be outside the installation, so updates never touch your databases. See Data and privacy for what is inside it.

Service settings##

The service reads patterm.env. It uses systemd's KEY="value" syntax, so do not source it from a shell. The installer writes PATH, HOME and SHELL from the account that installed it, so agents started by the service can find your CLIs.

Choose Open from, the password and Only me in Settings › Remote access. Applying a change restarts the web server only. Agents and terminals keep running and open pages reconnect.

To set things from the command line instead, run the service installer with the bundled Node. Stop the service first: the installer refuses to change access settings while Patterm is using the data directory.

systemctl --user stop patterm.service
~/.local/share/patterm/current/runtime/node \
  ~/.local/share/patterm/current/scripts/install-service.mjs \
  --remote-access tailscale
systemctl --user daemon-reload
systemctl --user start patterm.service

Keep the data directory fixed while agents are running. To move it, use Quit Patterm first and check that every patterm-terminal@ unit has stopped.

Desktop and server do not share data##

The desktop app and the server each have their own data directory. The desktop app keeps its data in ~/.config/patterm-desktop.

Only one Patterm can use a data directory at a time. Patterm takes a lock on it before opening the databases or starting anything. If you point a second Patterm at a directory that is in use, it stops with:

Patterm is already using <directory>, or its runtime lock is unavailable

To use both the desktop app and a server, pair them as hosts. See Multiple hosts.

What survives a restart##

An installed service runs each terminal in its own patterm-terminal@ unit, separate from patterm.service. This means:

• Stopping or restarting patterm.service does not stop your agents or commands. A native sleep keeps sleeping.
• When the service starts again it reconnects to the same terminals.
• Closing a browser, losing the network or putting your laptop to sleep does not stop anything.
• Patterm timers keep their deadlines. If one expires while the service is down, the callback is delivered after it reconnects.
• Tool calls an agent makes while the service is down can fail, and Patterm does not replay them.

A reboot, or a failure of a terminal host, ends the processes it was running. Patterm does not resume agents after a reboot. Resume each conversation yourself from the project's history. See Conversation history.

Stop everything##

systemctl --user stop patterm.service stops the web service and leaves agents running.

To stop agents too, open the command palette and choose Quit Patterm. Its confirmation tells you how many agents and commands across all projects will stop, including sleeps and Patterm timers. Quit stops every terminal host, including hosts from older versions. Saved conversations remain available to resume.

Update##

Rerun the installer with --update, as described in Installation. It stops the service, switches current to the new version, restarts the service and waits for /health. It keeps the new version and the one before it.

Running agents keep the version they started with. New sessions use the new version. Refresh your browser afterwards.

Backups before migrations##

When an update has database migrations to run, Patterm first copies both databases into backups/pre-migration-<time>/ in the data directory. The last two sets are kept. If the backup fails, for example because the disk is full, Patterm does not start rather than migrate without one. Uploads and images are not included.

To roll back an update that migrated the databases:

1. Use Quit Patterm and check that patterm.service and every patterm-terminal@ unit are inactive.
2. Move app.db, history.db and their -wal and -shm files out of the data directory, and keep them until you have checked the rollback.
3. Copy app.db and history.db from the newest backups/pre-migration-* set into the data directory. manifest.json in the set lists a SHA-256 hash for each copy.
4. Install the previous version by running the installer with --version <version> --allow-downgrade, adding --update if the service is active.

Uninstall##

Run the uninstaller described in Installation. It stops every Patterm agent and terminal, then removes the services, launcher and installed versions.

Related##

• Browser and phone access
• Multiple hosts
• Troubleshooting