# 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](#install-an-agent-cli).

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

> [!NOTE]
> macOS and Windows are not supported yet. Desktop apps for them are in progress.

## Install

Run the installer:

```sh
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:

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

## Start Patterm

### Desktop app

```sh
patterm
```

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

### Background service

```sh
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](https://patterm.com/docs/linux-server.md) and [Browser and phone access](https://patterm.com/docs/browser-and-phone.md).

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

To stop the service:

```sh
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`:

| CLI         | Command    |
| ----------- | ---------- |
| Claude Code | `claude`   |
| Codex       | `codex`    |
| OpenCode    | `opencode` |

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`:

```sh
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

```sh
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`:

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

## Related

- [Your first project](https://patterm.com/docs/first-project.md)
- [Linux server](https://patterm.com/docs/linux-server.md)
- [Troubleshooting](https://patterm.com/docs/troubleshooting.md)

---

This is one page of the Patterm documentation. The index of every page is at https://patterm.com/llms.txt.