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

{/* https://screenpi.pe */}

<Tip>want the fastest path? see the [5-minute quickstart →](/quickstart)</Tip>

## desktop app or CLI?

| choose      | if you want                                                                 |
| ----------- | --------------------------------------------------------------------------- |
| desktop app | visual timeline, pipes, connections, chat, settings, and guided permissions |
| CLI         | free local recording, REST API access, and terminal-first workflows         |

## 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, pipes, and AI connections — no terminal needed.

## CLI

```bash theme={null}
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={null}
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={null}
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={null}
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={null}
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={null}
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={null}
SCREENPIPE_NO_REMINDERS=1 npx -y screenpipe@latest record
```

or set it once in your shell:

```bash theme={null}
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, it serves an API on `localhost:3030`:

```bash theme={null}
# check health
curl http://localhost:3030/health

# search your screen history
curl "http://localhost:3030/search"
```

<Note>if you've enabled API auth in settings, add `-H "Authorization: Bearer <your-api-key>"` to these requests. by default the local API needs no auth.</Note>

## check and update your version

to ensure you're running the latest version:

```bash theme={null}
# 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={null}
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 (if enabled)

by default the local API on `localhost:3030` needs no auth. if you've turned on API auth in settings, get your key by running:

```bash theme={null}
npx -y screenpipe@latest auth token
```

then use it in curl:

```bash theme={null}
curl "http://localhost:3030/search?q=example" \
  -H "Authorization: Bearer <your-api-key>"
```

or set it as an environment variable:

```bash theme={null}
export SCREENPIPE_API_KEY=$(npx -y screenpipe@latest auth token)
curl "http://localhost:3030/search?q=example" \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY"
```

## 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={null}
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](/mcp-server))        |
| **cursor**         | add screenpipe MCP to your project ([guide](/mcp-server))  |
| **claude code**    | use screenpipe MCP or curl the API ([guide](/claude-code)) |
| **ollama**         | configure in app settings, use any local model             |

## what's next?

<CardGroup cols={2}>
  <Card title="browse pipes" icon="store" href="/pipe-store">
    see all available automations — day recap, standup, time tracking, and more
  </Card>

  <Card title="connect your AI" icon="server" href="/mcp-server">
    add screenpipe to Claude, Cursor, ChatGPT, or any AI tool
  </Card>

  <Card title="connect your apps" icon="plug" href="/connections">
    link Calendar, Google Docs, Notion, Obsidian for richer context
  </Card>

  <Card title="what can I do?" icon="lightbulb" href="/use-cases">
    explore use cases — loop closing, meeting notes, time tracking, and more
  </Card>

  <Card title="API recipes" icon="terminal" href="/api-recipes">
    copy-paste local API workflows for search, meetings, speakers, frames, and retention
  </Card>
</CardGroup>

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

[download screenpipe →](https://screenpi.pe/onboarding)