Install Pieces on Linux

Pick how you'd like to install Pieces. Flatpak is recommended for most distributions; Snap is a good fit for Ubuntu. Expand a method below for step-by-step setup of both PiecesOS and the Desktop App.

Works across most distributions — Fedora, Arch, Debian, Ubuntu, Linux Mint, and more.

Install with your software center Easiest

The graphical way — no terminal required. Download the Pieces repository file, then follow the steps below in your software center (GNOME Software, KDE Discover, or similar).

Download repository file
  1. 1Open the downloaded file to add the Pieces repository to your software center.
  2. 2Search for PiecesOS in your software center and install it.
  3. 3Search for the Pieces Desktop App and install it, then launch PiecesOS before opening the app.
or

Install via terminal

Prefer the command line? Run these commands in order.

  1. 1

    Add the Flathub repository, which provides the shared runtime dependencies Pieces requires.

    flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

    Safe to run even if Flathub is already set up — it's skipped if the repository already exists.

  2. 2

    Add the official Pieces repository, which hosts both PiecesOS and the Pieces Desktop App.

    flatpak remote-add --user --if-not-exists --from pieces-flatpak https://builds.pieces.app/pieces-flatpak-repo/pieces-flatpak.flatpakrepo

    The --user flag installs it for your account only, so no sudo is required.

  3. 3

    Install PiecesOS, the on-device engine that powers everything — Long-Term Memory, local AI, and MCP.

    flatpak install -y pieces-flatpak com.pieces.os

    This can take a few minutes while Flatpak downloads the required runtime dependencies.

  4. 4

    Install the Pieces Desktop App, your hub for saving, searching, and managing snippets, screenshots, and developer resources.

    flatpak install -y pieces-flatpak com.pieces.pfd
  5. 5

    Start PiecesOS first. It runs as a background service the Desktop App connects to, and the app won't launch it automatically.

    flatpak run com.pieces.os
  6. 6

    Once PiecesOS is running, launch the Pieces Desktop App. After the first launch, both appear in your application menu.

    flatpak run com.pieces.pfd

    Always start PiecesOS before the Desktop App.

Full Flatpak guideRequirements, updating, uninstalling, and troubleshooting.

A good fit for Ubuntu. Requires snapd and sudo access.

Install via terminal

Ubuntu 22.04+ with snapd is required. Run these commands in order — Snap installs system-wide, so they use sudo.

  1. 1

    Install PiecesOS, the on-device engine that powers everything — Long-Term Memory, local AI, and MCP.

    sudo snap install pieces-os
  2. 2

    Connect PiecesOS to the system's process-control interface, which it needs to run correctly.

    sudo snap connect pieces-os:process-control :process-control
  3. 3

    Install the Pieces Desktop App.

    sudo snap install pieces-for-developers
  4. 4

    Connect the remaining system interfaces. This prints a command — copy and run it to finish setup.

    pieces-os.doctor

    Required for full functionality, including features like LTM audio.

  5. 5

    Launch the Pieces Desktop App. After the first launch, it also appears in your application menu.

    pieces-for-developers
Full Snap guideRequirements, connecting interfaces, updating, and troubleshooting.