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

# Dev Server Runbook

> Runbook for running and troubleshooting the three local development services.

# Dev Server Runbook

**Prerequisites:** Node.js 22+ and [corepack](https://nodejs.org/api/corepack.html) enabled. See [Architecture](/architecture) for how the three services interact.

This project runs 3 local services:

* Site: `http://localhost:3000`
* Content Studio: `http://localhost:4100`
* Orchestrator: `http://localhost:4200`

Use the managed workflow commands from repo root.

## Start

```bash theme={null}
pnpm dev:start
```

## Check Status

```bash theme={null}
pnpm dev:status
```

Expected output when healthy:

* `running`
* `pid: ...`
* `log: .../.run/devctl/dev.log`

Note: `pnpm dev:status` returns exit code `1` when stopped. That is expected.

## Restart

```bash theme={null}
pnpm dev:restart
```

## Stop

```bash theme={null}
pnpm dev:stop
```

## Logs

```bash theme={null}
pnpm dev:logs
```

## Full Health Check

```bash theme={null}
curl -sS -o /dev/null -w "3000:%{http_code}\n" http://localhost:3000/
curl -sS -o /dev/null -w "4100:%{http_code}\n" http://localhost:4100/
curl -sS http://localhost:4200/health
```

Healthy responses:

* `3000:200`
* `4100:200`
* `{"ok":true}`

## Troubleshooting

1. If site/Content Studio/orchestrator is unreachable:
   * Run `pnpm dev:status`
   * If `stopped`, run `pnpm dev:start`
2. If status says `running` but UI fails:
   * Run `pnpm dev:logs`
   * Run the curl health checks above
3. If ports are occupied by stale processes:
   * Run `pnpm dev:stop`
   * Run `pnpm dev:start`
4. Deep diagnostics:
   * Run `pnpm dev:doctor`