Install Screenpipe on macOS, Windows, and Linux

Install Screenpipe on macOS, Windows, or Linux. Record everything on screen and search screen history on Mac, Windows, and Linux. Start recording in minutes.

Want the fastest path? See the 5-minute quickstart →

Free and paid installation options

Downloading the official desktop app is not the same as choosing a free source build. Check the current checkout for trial eligibility, payment details, renewal, and cancellation terms before starting.

Choose	What it provides	License and payment
Official desktop app	Prebuilt installer, visual timeline, chat, scheduled tasks, connections, and updates	Governed by your app license or subscription and the Terms of Service
CLI	Terminal recording, local search, and REST API access	Check the license and distribution terms for the version you install
Build from source	Build and maintain the recorder or desktop app yourself	Current source uses the Screenpipe Commercial License

The current source license permits personal non-commercial use, non-profit/educational/research use, and an evaluation period described in the license. Commercial use requires a paid commercial license. It is not an MIT license; source availability does not mean unrestricted free business use.

Why does the downloaded app ask for a credit card?

The official app uses its checkout and account entitlement flow. Trial offers can require payment details; review the renewal and cancellation terms shown before confirming. If you already paid, use the purchase email and follow the account checks before buying again. Building from source is a separate installation and licensing path, not a way to unlock the official app.

Your Screenpipe purchase and your AI provider access are also separate. See which AI access you need.

Desktop app (recommended)

Download the desktop app and follow the installation instructions. Works on macOS, Windows, and Linux.

The app manages recording, settings, search, scheduled tasks, and AI connections — no terminal needed.

CLI

npx -y screenpipe@latest record

This starts the Screenpipe daemon in the background and continuously records your screen. Data is stored in ~/.screenpipe/ on your local machine.

Troubleshooting: “npx -y Screenpipe@latest record” not working

If the command fails, try these fixes in order:

Unsupported platform:

node -p "process.platform + '-' + process.arch"

if the output is not darwin-arm64, darwin-x64, linux-x64, or win32-x64, your platform is not supported.

Missing platform package (macOS/Windows/Linux):

npx -y screenpipe@latest --version

the CLI needs the platform-specific binary. re-running with npx -y screenpipe@latest pulls a fresh copy.

macOS: binary blocked by Gatekeeper: If you see “app is damaged” or “permission denied”, run:

xattr -d com.apple.quarantine ~/.npm/_npx/*/node_modules/screenpipe*/bin/screenpipe

or use the desktop app instead — it handles permissions automatically.

Linux: missing system libraries:

sudo apt install libasound2-dev ffmpeg  # ubuntu/debian
sudo dnf install alsa-lib ffmpeg         # fedora

Windows: .NET runtime missing: The Screenpipe installer includes .NET, but if you’re using the CLI only, install .NET 8.0.

Port 3030 already in use: If Screenpipe is already running, the CLI will fail to bind. Check for existing processes:

lsof -i :3030     # macOS/Linux
netstat -ano | findstr :3030  # Windows

Still stuck? ask in Discord.

Suppress CLI reminders (optional)

When running npx -y screenpipe@latest record, the CLI prints a friendly reminder every 5 minutes to download the desktop app. If you prefer to run the CLI silently, disable the reminders:

SCREENPIPE_NO_REMINDERS=1 npx -y screenpipe@latest record

Or set it once in your shell:

export SCREENPIPE_NO_REMINDERS=1
npx -y screenpipe@latest record

Access your recorded timeline

After starting the CLI, you have three ways to access your screen history:

1. Desktop app (easiest) — download the Screenpipe app for a visual timeline and built-in search
2. REST API — query recorded content directly via curl or code (see below)
3. AI assistants — connect Claude, Cursor, or other tools via MCP

Verify it’s running

Once Screenpipe starts, its local API normally listens on localhost:3030. Check capture health first:

curl --fail-with-body http://localhost:3030/health

/health does not require authentication. Protected routes can require a token. Retrieve it locally and use a bearer header:

SCREENPIPE_API_KEY=$(npx -y screenpipe@latest auth token)
curl --fail-with-body "http://localhost:3030/search?limit=1" \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY"

Check that the result contains recent activity. A healthy server alone does not prove that screen or audio capture is working. For an empty result, check permissions and missing recordings.

Check and update your version

To ensure you’re running the latest version:

# check your current version
npx -y screenpipe@latest --version

To update to the latest version, just run with @latest — it always pulls the newest release:

npx -y screenpipe@latest record

The latest version is always available at npm. If you’re on an older version, you’ll see a warning when you run npx -y screenpipe@latest record.

API authentication

Check Require API Authentication in your app settings. CLI authentication is enabled by default in current versions; use the installed version’s settings when diagnosing older installations.

Get the local token with npx -y screenpipe@latest auth token and pass it in an Authorization: Bearer header as above. Keep tokens out of shared URLs, screenshots, logs, and chat. An AI provider key is not the Screenpipe local API token.

If you get 401 or 403, verify the token belongs to the same running Screenpipe instance and data directory. Refresh client credentials after rotating the token. Keep authentication enabled when making Screenpipe reachable from another machine.

Connect to AI

Screenpipe works with any AI that supports MCP or HTTP APIs.

The fastest path is one command — it installs the Screenpipe skills and registers the MCP server for your agent:

npx -y screenpipe@latest agent setup <target>

Where <target> is one of openclaw, hermes, claude-code, claude-desktop, codex, cursor, or windsurf. Add --api-url <URL> if Screenpipe runs on another machine.

Prefer to wire it up manually? Here’s where each tool plugs in:

Integration	How
Claude desktop	Add Screenpipe as MCP server (guide)
Cursor	Add Screenpipe MCP to your project (guide)
Claude Code	Use Screenpipe MCP or curl the API (guide)
Ollama	Configure in app settings, use any local model

What’s next?

Browse scheduled tasks

See all available automations — day recap, standup, time tracking, and more

Connect your AI

Add Screenpipe to Claude, Cursor, ChatGPT, or any AI tool

Connect your apps

Link Calendar, Google Docs, Notion, Obsidian for richer context

What can I do?

Explore use cases — loop closing, meeting notes, time tracking, and more

API recipes

Copy-paste local API workflows for search, meetings, speakers, frames, and retention

• Search your screen history — find anything you’ve seen
• API reference — REST API endpoints and parameters
• Troubleshooting — fix common issues
• Join our Discord — get help from the community

Download Screenpipe →