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

# percio start

> Start the local Percio daemon

Start the daemon that powers the Percio CLI. You rarely need to run this explicitly — other commands auto-start the daemon — but you will use it for MCP mode, pinned ports, and troubleshooting.

## Synopsis

```bash theme={null}
percio start [options]
```

## Options

| Flag              | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `-d, --detach`    | Run the daemon in the background and return immediately.            |
| `--mcp`           | Start with the MCP server enabled on stdio. Used by `percio-mcp`.   |
| `--port <number>` | Pin the daemon to a specific port instead of picking one at random. |

## Examples

**Foreground (default).** Best for integrated terminals where you want the shell to stay usable while the daemon runs:

```bash theme={null}
percio start
```

**Detached.** Runs in the background, returns immediately, and prints the port it bound to:

```bash theme={null}
percio start -d
# Daemon started in background at http://127.0.0.1:52431. Use percio stop to stop.
```

**Pinned port.** Useful when you're integrating with something that needs to know the port ahead of time:

```bash theme={null}
percio start --port 5174
```

**MCP mode.** Starts the daemon with the MCP server attached to stdio. This is what `percio-mcp` does under the hood, and what your Cursor config invokes:

```bash theme={null}
percio start --mcp
```

## What it does

* Binds an HTTP server to `127.0.0.1` (localhost only).
* Writes a lockfile so future CLI commands know how to reach it.
* Creates `.perciorc.json` in the current directory if one doesn't exist.

## Auto-start

Every other CLI command (`percio test`, `percio personas list`, etc.) will auto-start the daemon if one isn't running. You don't need to call `percio start` unless you want one of the scenarios above.

## Checking it's running

After a detached start, the daemon port is printed to your terminal. You can also check via any CLI command that talks to the daemon — they'll fail fast if the daemon is unreachable.

## What's next

* [percio stop](/agent/cli/stop)
* [The local daemon](/agent/daemon)