> ## Documentation Index
> Fetch the complete documentation index at: https://docs.screenpipe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!TIP]
>
> Want the fastest path? See the [5-minute quickstart →](https://docs.screenpipe.com/quickstart.md)

## Free and paid installation options

Downloading the official desktop app is not the same as choosing a free source build. Check the [current checkout](https://screenpi.pe/onboarding) 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](https://screenpi.pe/terms) |
| 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](https://github.com/screenpipe/screenpipe/blob/main/LICENSE.md) |

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](https://docs.screenpipe.com/faq.md#billing-license-and-account) 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](https://docs.screenpipe.com/local-or-cloud-ai.md#screenpipe-plans-and-ai-subscriptions).

## Desktop app (recommended)

Download the [desktop app](https://screenpi.pe/onboarding) 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

```bash theme={"system"}
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:**

```bash theme={"system"}
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):**

```bash theme={"system"}
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:

```bash theme={"system"}
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:**

```bash theme={"system"}
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](https://dotnet.microsoft.com/en-us/download/dotnet/8.0).

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

```bash theme={"system"}
lsof -i :3030     # macOS/Linux
netstat -ano | findstr :3030  # Windows
```

Still stuck? [ask in Discord](https://discord.gg/screenpipe).

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

```bash theme={"system"}
SCREENPIPE_NO_REMINDERS=1 npx -y screenpipe@latest record
```

Or set it once in your shell:

```bash theme={"system"}
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](https://screenpi.pe/onboarding) 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:

```bash theme={"system"}
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:

```bash theme={"system"}
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](https://docs.screenpipe.com/missing-recordings.md).

## Check and update your version

To ensure you're running the latest version:

```bash theme={"system"}
# 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:

```bash theme={"system"}
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:

```bash theme={"system"}
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](https://docs.screenpipe.com/mcp-server.md)) |
| **Cursor** | Add Screenpipe MCP to your project ([guide](https://docs.screenpipe.com/mcp-server.md)) |
| **Claude Code** | Use Screenpipe MCP or curl the API ([guide](https://docs.screenpipe.com/claude-code.md)) |
| **Ollama** | Configure in app settings, use any local model |

## What's next?

> [card] [Browse scheduled tasks](https://docs.screenpipe.com/task-library.md)
>
> See all available automations — day recap, standup, time tracking, and more

> [card] [Connect your AI](https://docs.screenpipe.com/mcp-server.md)
>
> Add Screenpipe to Claude, Cursor, ChatGPT, or any AI tool

> [card] [Connect your apps](https://docs.screenpipe.com/connections.md)
>
> Link Calendar, Google Docs, Notion, Obsidian for richer context

> [card] [What can I do?](https://docs.screenpipe.com/use-cases.md)
>
> Explore use cases — loop closing, meeting notes, time tracking, and more

> [card] [API recipes](https://docs.screenpipe.com/api-recipes.md)
>
> Copy-paste local API workflows for search, meetings, speakers, frames, and retention

* [Search your screen history](https://docs.screenpipe.com/search-screen-history.md) — find anything you've seen
* [API reference](https://docs.screenpipe.com/cli-reference.md) — REST API endpoints and parameters
* [Troubleshooting](https://docs.screenpipe.com/troubleshooting.md) — fix common issues
* [Join our Discord](https://discord.gg/screenpipe) — get help from the community

[Download Screenpipe →](https://screenpi.pe/onboarding)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.