Skip to content

Local development

How to run the stack on your machine, and the realities of doing voice dev on a Mac.

The Make targets

# Mac dev — uses compose.cloud.yaml (older shape, predates the pivot)
make dev             # cloud (compose) + sudoedge native (foreground, real mic)
make dev-cloud-only  # cloud only, no native edge / no mic
make dev-stop        # stop compose
make dev-clean       # nuke volumes + per-user containers + edge venv

# Prod stack (what actually runs on the VPS). Needs deploy/.env
make prod-up         # compose.prod.yaml up -d --build
make prod-status     # ps
make prod-logs       # logs -f
make prod-rebuild    # force-recreate

# Lint — syntax check only, there is no test suite
make lint            # python3 -m compileall on sudoedge + cloud

# Wake-word diagnostic (Mac only; native mic)
make wake-diag

make dev* predates the pivot

The make dev targets use compose.cloud.yaml (the older shape, still references things like sudo-relay). The canonical stack is compose.prod.yaml. The dev targets need a refresh; if you're verifying real behavior, prefer the prod compose.

Why the edge runs natively on Mac

sudoedge runs as a native foreground process, not in a container, during dev — because Docker on macOS can't share the host microphone with a container. make dev brings up the cloud in compose and sudoedge natively so you get a real mic.

There is no test suite

No pytest / jest / etc. You verify changes by:

  1. Reading the code (the first and cheapest check).
  2. make lint — a compileall syntax check.
  3. Deploy + smoke-test in the browser: /chat, /integrations, /admin/settings, and /docs.

For edge changes specifically: test on a real Pi before tagging — hardware bugs don't surface any other way.

The /docs wiki locally

The wiki is built with MkDocs Material. To preview it with live-reload while editing:

# from repo root, if mkdocs-material is installed locally
mkdocs serve -f cloud/wiki/mkdocs.yml

Otherwise it's built into the sudo-api image at build time and served at /docs. See Repo layout for where the wiki source lives.