Skip to main content
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

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:

​
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