# Setup

> Get a Menace Voice dev environment running and learn the daily commands.

Menace Voice is a Next.js UI (`ui/`), a FastAPI backend (`api/`), and a Pipecat-based voice pipeline (`pipecat/`, a git submodule), backed by Postgres, Redis, and MinIO.

## Set up

You need Git, a local Docker engine (such as Docker Desktop), and VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

1. Obtain the Menace Voice source package and clone it locally:

```bash
git clone --recurse-submodules https://github.com/drewsephski/menace-voice.git
cd menace-voice
```

2. Open the folder in VS Code and run **Dev Containers: Reopen in Container**. The first build takes several minutes — it starts Postgres, Redis, and MinIO, seeds the Python venv, creates the `.env` files, and installs UI dependencies. Later opens are fast.

3. Start the backend from a terminal inside the container. The script waits for the health check and prints a status summary, so when it exits successfully the backend is up:

```bash
bash scripts/start_services_dev.sh
```

4. Start the UI from a second terminal inside the container:

```bash
cd ui && pnpm run dev --hostname 0.0.0.0
```

5. Open the app at `http://localhost:3000`.

If these steps do not work for you, contact your designated Menace support channel.

<AccordionGroup>
<Accordion title="Need to configure source remotes manually?">
Run `bash scripts/setup_fork.sh` once. It prompts for your source URL, configures the remotes, initializes the Pipecat submodule, and creates the local environment files. See [Fork and upstream remotes](/contribution/reference#fork-and-upstream-remotes).
</Accordion>
<Accordion title="No VS Code? No devcontainer at all?">
The devcontainer also runs headless via the [Dev Container CLI](/contribution/reference#dev-container-cli), or you can run everything [directly on your host](/contribution/reference#host-managed-setup).
</Accordion>
</AccordionGroup>

## Daily workflow

| What | How |
| --- | --- |
| Restart the backend | Re-run `bash scripts/start_services_dev.sh` — it stops the old processes first |
| Stop the backend | `bash scripts/stop_services.sh` |
| Backend logs | `tail -f logs/latest/*.log` |
| Code reload | Edits under `api/` auto-reload; `ari_manager`, `campaign_orchestrator`, and `arq` need a backend restart |
| Rebuild the container | Only when `.devcontainer/`, `api/requirements*.txt`, or `pipecat/` change — plain source edits never need it |
| Sync the pipecat submodule | `git submodule update --init --recursive` after pulling a submodule bump |

## Debugging

The repo ships debug configurations in `.vscode/launch.json` for every backend service and for pytest. To run under the debugger instead of the start script:

1. Stop the script-managed backend if it is running, so the ports are free:

```bash
bash scripts/stop_services.sh
```

2. In VS Code's **Run and Debug** panel, pick a configuration and press F5:

| Configuration | What it runs |
| --- | --- |
| **API: Uvicorn (reload)** | The FastAPI backend, with auto-reload (port from `UVICORN_PORT` in `api/.env`, default 8000) |
| **API: Arq worker (watch)** / **API: Campaign orchestrator** / **API: ARI manager** | The other backend services — launch them alongside Uvicorn as needed |
| **Tests: API (pytest, full suite / current file)** | pytest under the debugger, against `api/.env.test` |
| **Tests: Pipecat (pytest, current file)** / **Python: Current file** | Debug a pipecat test or any standalone script |

All configurations load `api/.env` (test configs use `api/.env.test`) and set `justMyCode: false`, so you can step into FastAPI and pipecat code — breakpoints in the `pipecat/` submodule work because it is installed editable. Inside the devcontainer the Python interpreter is preselected; on a host-managed setup, pick `./venv/bin/python` via **Python: Select Interpreter** first.

## Repository layout

| Path | What's there |
| --- | --- |
| `ui/` | Next.js frontend — the workflow builder, dashboard, and agent editor |
| `api/` | FastAPI backend — REST API, campaign orchestration, telephony, ARQ background workers |
| `pipecat/` | Git submodule for the voice pipeline (STT → LLM → TTS) |
| `docs/` | This documentation site, written in MDX, previewed with `pnpm dlx @upstash/docs7@0.1.1 dev ./docs` |
| `sdk/` | Python/TypeScript SDKs for driving Menace Voice programmatically |
| `scripts/` | Setup, deployment, and update scripts |
| `deploy/` | nginx and coturn config templates used by remote deployment |

## Contributing a change

1. Create a branch and make your change.
2. Push the branch to your configured source remote and open a pull request.
3. A maintainer reviews and merges.

For bug reports and feature ideas, include reproduction steps, expected behavior, and relevant logs. Contact your designated Menace support channel if you need help while working.

Deploying your own build instead of contributing upstream? See [Deployments](/deployment/introduction) instead.