Dev Container + `make dev` workflow¶

This document covers two paths to a working build environment:

Dev container (VS Code / GitHub Codespaces) — zero manual setup
Local machine with make dev / make dev-deps

Dev container (VS Code / Codespaces)¶

The repo ships a .devcontainer/ config recognized by VS Code and GitHub Codespaces.

Prerequisites¶

VS Code with the Dev Containers extension (ms-vscode-remote.remote-containers)
Docker Desktop (local) — OR use GitHub Codespaces (no local Docker needed)

Open in a container¶

# Clone the repo and open in VS Code
git clone https://github.com/Blackrim-Vox/blackrim-vox.git
code blackrim-vox

VS Code detects .devcontainer/devcontainer.json and prompts:

Reopen in Container

Click it. The first build downloads the base image and installs deps (~2–5 min).

Once inside the container:

make test      # full unit-test suite — should pass green
make check-air-gap
make check-no-telemetry

What the container provides¶

Component	Detail
Base image	`mcr.microsoft.com/devcontainers/go:1.22` (Ubuntu 24.04)
Go toolchain	1.22 (matches `go.mod`)
C toolchain	gcc + clang for CGO (required by `miniaudio`)
Audio libs	libasound2-dev, libpulse-dev
ONNX Runtime	v1.18.0 (required by `onnxruntime_go`)
ffmpeg	audio test fixtures
GitHub CLI	`gh` — authenticated via `postCreateCommand` or `gh auth login`
Forwarded port	9101 (metrics endpoint)

GitHub Codespaces¶

Click Code → Codespaces → Create codespace on main in the GitHub UI. The same .devcontainer/ config applies. make test passes without any additional setup.

Local machine (`make dev` / `make dev-deps`)¶

Install system deps (macOS)¶

make dev-deps

This runs brew install entr ffmpeg. On Linux / other Unix, install equivalent packages (entr is in most distro package managers as entr).

Live-reload dev loop¶

make dev

This watches all .go files with entr and re-runs go run ./cmd/vox listen --asr=echo --sink=local-file on every change.

--asr=echo — echo ASR backend (no network, no API key)
--sink=local-file — writes segments to a local file instead of any cloud sink
Port 9101 exposes Prometheus metrics while the process is running

If entr is not installed, make dev falls back to a single non-watching go run and prints instructions.

Quality gates¶

make check-air-gap        # build + air-gap integration test
make check-no-telemetry   # verify telemetry is off in the default build

Both gates must pass before opening a pull request.

Troubleshooting¶

CGO errors (malgo, onnxruntime_go): These packages require C headers. Inside the dev container they are pre-installed. Locally, ensure gcc (macOS: xcode-select --install) and the ONNX Runtime shared library are on your CGO_LDFLAGS / CGO_CFLAGS paths.

entr not found: Run make dev-deps (macOS) or apt install entr (Debian/Ubuntu), then retry make dev.

Port 9101 already in use: Another vox process is running. lsof -i :9101 to find it, kill <pid> to free the port.

Dev Container + make dev workflow¶