Installation

Patterm installs on Linux with one command, as a desktop app, a background service, or both.

Requirements##

• Linux on x64 or arm64, with systemd.
• curl, tar, gzip and sha256sum, which the installer checks for.
• A graphical session to use the desktop app. The background service needs none.
• At least one agent CLI that you have installed and signed in to. See Install an agent CLI.

You do not need Node, pnpm or Rust. The release bundles what it needs.

Install##

Run the installer:

curl -fsSL https://github.com/hjbdev/patterm/releases/latest/download/install.sh | bash

It downloads the release for your architecture and checks it against the release's SHA-256. If you have minisign installed, it also checks the release manifest's signature on a first install. Without it, the installer says the signature was not checked.

Each version unpacks into ~/.local/share/patterm/versions/<version>. The installer links ~/.local/bin/patterm and adds a desktop entry. To install somewhere else, set PATTERM_HOME before running it.

If ~/.local/bin is not on your PATH, add it so the patterm command works.

To install a specific release, including a pre-release:

curl -fsSL https://github.com/hjbdev/patterm/releases/latest/download/install.sh | bash -s -- --version 1.3.0-beta.1

Start Patterm##

Desktop app##

patterm

This opens the desktop window. You can also start it from your desktop's application launcher.

Background service##

patterm --headless

This starts a systemd user service without opening a window. Open http://localhost:8787 in a browser on that machine. Closing the browser does not stop your agents.

Starting the service does not make it start at login or keep running after you log out. For that, and for opening Patterm from other devices, see Linux server and Browser and phone access.

The desktop app and the service keep separate data, so projects added in one do not appear in the other.

To stop the service:

systemctl --user stop patterm.service

Install an agent CLI##

Patterm does not install agent CLIs for you. Install the ones you want from their own documentation and sign in to each one before using it in Patterm.

Patterm finds these on your PATH:

If none are found, the Launch agent menu says "No agent CLIs found on PATH". The background service uses the PATH of the account that installed it, so install the CLIs for that account.

Update##

To update, rerun the installer with --update:

curl -fsSL https://github.com/hjbdev/patterm/releases/latest/download/install.sh | bash -s -- --update

If the background service is running, the installer refuses to run without --update. With it, the installer stops the service, switches to the new version, restarts it, and waits for the service to answer its health check. The previous version stays on disk so you can roll back.

The installer will not install an older version than the one you have unless you add --allow-downgrade. An older Patterm may not be able to open a database that a newer one has migrated.

If you used an earlier from-source install in ~/.local/share/patterm-desktop, --update moves you to the release and removes that directory once the new service is healthy. It keeps the directory while any process, such as an agent started before the update, still runs from it. A later --update removes it.

Uninstall##

curl -fsSL https://github.com/hjbdev/patterm/releases/latest/download/uninstall.sh | bash

This stops every Patterm agent and terminal, then removes the services, the patterm launcher and the installed versions. It asks before deleting your data. If it cannot confirm that Patterm stopped, it removes nothing.

To skip the questions, add --yes with either --keep-data or --delete-data:

curl -fsSL https://github.com/hjbdev/patterm/releases/latest/download/uninstall.sh | bash -s -- --yes --keep-data

Related##

• Your first project
• Linux server
• Troubleshooting