Issues | macOS

Learn about what troubleshooting steps to take if PiecesOS or the Pieces Desktop App isn’t working as expected on your macOS device.

Displaying macos.png

Installation & Updating Fixes

PiecesOS and the Pieces Desktop App can be downloaded using several installation methods, and they can be updated differently depending on the method used.

You can also find information below on how to determine your Apple device's CPU architecture and OS version.

All your Pieces data, including snippets, tags, embeddings, LTM-2 memory, settings, logs, and Pieces Copilot history, is securely stored in the com.pieces.os and com.pieces.pfd folders on your device.

This gives you full control over backups, sharing, and privacy.

Database & Log Paths

You can find your database and support logs at the path below for your specific platform.

  • macOS—~/Library/com.pieces.os/

  • Windows—C:\Users\<username>\Documents\com.pieces.os\

  • Linux—~/.local/share/com.pieces.os/

Don’t forget to switch username with our actual system username.

Logs, Backups & Cloud Functionality

This dedicated On-Device Storage documentation provides more information about finding your logs, creating manual backups outside of the Pieces Desktop App, and opting in to cloud-only features.

  • Sharing Logs—Zip the latest 2–3 files from …/production/support/logs/ and attach them to your issue or DM.

  • Backup & Reset—Copy com.pieces.os to back up your database—or copy zip it, and rename it something other than production to reset your database.

  • Cloud Functionality—Nothing moves off-device unless you enable Personal Cloud or call a third-party model (e.g. OpenAI).

Manual Installation Methods

If you’re experiencing difficulties installing PiecesOS or the Pieces Desktop App, you can manually install both software by downloading the standalone files or using terminal commands.

If you’re unsure which .dmg or .pkg you need based on your device’s CPU, click here.

via PKG Files

Make sure to select the correct Pieces .pkg for your macOS device—Apple Silicon (ARM) or Intel.

Apple Silicon (ARM)

Intel

Download Pieces PKG for macOS (Apple Silicon / ARM)

Download Pieces PKG for macOS (Intel)

via DMG Files

Make sure to select the correct Pieces .dmg files for your macOS device—Apple Silicon (ARM) or Intel.

Apple Silicon (ARM)

Intel

Download PiecesOS DMG for macOS (ARM)

Download PiecesOS DMG for macOS (Intel)

Download Pieces Desktop App DMG for macOS (ARM)

Download Pieces Desktop App DMG for macOS (Intel)

via Homebrew

A singular brew command, brew install—- cask pieces, automatically manages installing PiecesOS and the Pieces Desktop App.

Versions & Updates

Many issues can stem from out-of-date plugins, extensions, the desktop app, or PiecesOS.

Updating PiecesOS

To restart and check for updates to PiecesOS on macOS:

  1. Restart PiecesOS

  2. Ensure PiecesOS is running (look for the Pieces Icon in your system tray)

  3. Check for and install available updates

Updating the Pieces Desktop App

Updating the Pieces Desktop App on Windows and macOS systems can be done by clicking the user icon to the right of the search bar at the top of the Pieces Desktop Window, then clicking Check for Desktop App Updates or Check for PiecesOS Updates.

To check the Pieces Desktop App for updates on macOS:

  1. Open the Pieces Desktop App

  2. Click the user icon to the right of the search bar at the top of the main app view

  3. Click Check for Desktop App Updates

You can also click Check for PiecesOS Updates as an alternative to doing so in from the PiecesOS system window in your taskbar.

Common Installation Issues

There are a range of common install issues on Apple devices, like having an out-of-date OS version or selecting the wrong installation package.

Checking OS Version

Pieces Suite applications require a minimum macOS version of macOS 13.0 (Ventura). If you’re experiencing installation issues, you should first check your OS version to make sure it’s up-to-date.

To determine your Apple device’s version of macOS:

  1. Click the Apple icon in the top-left corner of your screen

  2. Select About This Mac

  3. Under your device name (i.e., MacBook Air), look for the last line on the list, titled macOS

The macOS line will report what version of macOS installed, e.g., Sequoia 15.1.1.

Checking CPU Type

Intel and Apple Silicon (ARM) devices run on entirely separate CPU architectures, so downloading the wrong package for your Apple device can cause apps from the Pieces Suite to be rendered useless.

To determine what CPU architecture your Apple device utilizes:

  1. Click the Apple () icon in the top-left corner of your screen.

  2. Select About This Mac, and look for the Overview section. The first line will contain your CPU type:

  • Apple Silicon / ARM: You will see an M-Series processor, e.g., Apple M3

  • Intel: You will see an Intel processor, e.g., 2.6 GHz Intel Core i7

Once you’ve determined your CPU architecture, download the correct installation package accordingly.

Restart & Retry

If installation fails due to having an outdated version of macOS or installing the wrong package for your device’s architecture, restart your machine and try the installation again from scratch.

If the problem persists, please open a GitHub issue for further assistance, or book a call with our engineers.

Updated on
Cross-Platform
Windows