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

# The local daemon

> How the Percio CLI talks to your machine

The Percio CLI doesn't do the browser work itself — it talks to a local **daemon** that handles Playwright, manages the test lifecycle, and proxies requests to the Percio API.

## Why the daemon exists

* **Browser reuse.** Playwright is expensive to start up. A long-running daemon keeps the browser context warm across commands.
* **Isolation.** The daemon runs in its own process so CLI commands return fast even while a test is running.
* **MCP integration.** The MCP server runs inside the daemon — starting the daemon with `--mcp` gives you a ready MCP endpoint on stdio.

## You mostly don't have to think about it

Every CLI command auto-starts the daemon if one isn't running. `percio test` and `percio personas list` will spin it up transparently the first time you run them. You don't need to `percio start` manually unless:

* You're running the MCP server (`percio start --mcp`).
* You want the daemon pinned to a specific port (`percio start --port 5174`).
* You're debugging a stuck daemon and want to start it in the foreground to see logs.

## How it listens

The daemon binds to `127.0.0.1` (localhost only — it's never reachable from the network) on a random port by default. The chosen port is recorded in a lockfile that the CLI reads on every invocation.

## Starting and stopping explicitly

```bash theme={null}
percio start        # foreground — useful for seeing daemon logs
percio start -d     # detached — runs in the background and returns immediately
percio stop         # shuts the daemon down
```

See:

* [percio start](/agent/cli/start)
* [percio stop](/agent/cli/stop)

## What happens when a command can't reach the daemon

If the lockfile is stale (daemon crashed without cleaning up, for example), the CLI will either start a fresh daemon or report a port conflict. Running `percio stop` followed by the failing command usually clears it.

## What's next

* [percio start](/agent/cli/start)
* [percio stop](/agent/cli/stop)
* [Troubleshooting](/agent/troubleshooting)