Rakkr is a centrally managed Linux audio recording platform built on one stubborn idea: a recording failure should surface while the session can still be saved, not the morning after.
Website · Documentation · Quick start · Architecture · Reference
Rakkr records audio on managed Linux nodes, watches the audio while it captures, and gives operators one console to start, schedule, monitor, and ship every recording — with an audit trail behind every privileged action.
It is four parts working together:
- 🧠 a controller API (Hono/Node) for auth, RBAC, audit, inventory, recordings, jobs, schedules, settings, health, uploads, and metrics;
- 🖥️ a React operator console for day-to-day operations;
- 🦀 a Rust recorder agent on each node that captures audio, samples meters, scores quality, manages a local cache, and syncs with the controller;
- 🗄️ Postgres + Drizzle for persistence — with JSON/in-memory fallback so the controller runs without a database.
An optional Dockerized Ansible runner provisions and updates recorder nodes over SSH.
Most room recording setups fail silently — a muted channel, a stuck flatline, a full disk — and nobody finds out until playback. Rakkr treats the recording as something to be measured and proven:
| Concern | How Rakkr answers it |
|---|---|
| Is the node alive? | Heartbeats, runtime inventory, automatic offline detection |
| Is the audio path trustworthy? | ALSA-first capture, PipeWire/JACK presets, pinned command templates |
| Is the input any good? | Live clipping, flatline, low-signal, channel-correlation, noise, speech & SNR scoring |
| Can we make speech clearer? | In-process DeepFilterNet3 / RNNoise enhancement for recordings and live listen, raw always kept |
| Can we recover with evidence? | Local health logs, synced health events, full audit trail, job-state transitions |
| Can we test without a room? | Fake-controller smokes, ALSA loopback, a golden speech fixture, deterministic fault lanes |
| Do outputs keep moving? | Local cache, controller upload runner, retry queue, multiple SMB/S3 destinations, retention after confirmed upload |
flowchart LR
room["Room audio"] --> agent["🦀 Recorder agent"]
agent -->|"capture · meters · health"| cache["💾 Local cache"]
agent <-->|"encrypted HTTP / WS"| api["🧠 Controller API"]
cache -->|"upload raw + enhanced"| api
api -->|"upload runner · SMB/S3 fan-out"| storage["☁️ SMB / S3"]
api <--> db[("Postgres + Drizzle")]
api --> ui["🖥️ Operator console"]
api --> metrics["📈 /metrics → Prometheus / Grafana"]
The agent uploads recordings to the controller; the controller's upload runner is what pushes them out to one or more SMB/S3 destinations. Nodes never talk to object storage directly.
Read the architecture overview for how the control loop, RBAC, and evidence channels fit together.
Rakkr uses mise as its toolchain and task runner.
mise trust
mise run setup # install pinned toolchains + dependencies
Copy-Item .env.example .env
mise run services:up # local Postgres in Docker
mise run dev # controller API + web console| Surface | URL |
|---|---|
| Web console | http://localhost:5173 |
| API health | http://localhost:8787/healthz |
| Metrics | http://localhost:8787/metrics |
Sign in with [email protected] / rakkr-local-dev-password. Prefer containers?
docker compose up --build brings up the whole stack. Full walkthrough:
Quick start.
Complete docs live at docs.rakkr.org:
| Section | Start here |
|---|---|
| 🚀 Getting started | Introduction · Quick start · Core concepts |
| 🏗️ Architecture | Overview · Controller API · Recorder agent · Web console · Data model |
| 📖 Guides | Auth & RBAC · Nodes · Recording · Audio enhancement · Scheduling · Health watchdog · Storage & uploads · Transport security · Node lifecycle |
| 🔧 Reference | Configuration · Recorder agent CLI · API endpoints · Permissions · Metrics · Tasks |
| 🛠️ Operations | Deployment · Observability |
| 🤝 Contributing | Development · Testing · Baselines |
apps/api/ Hono controller API and API tests
apps/web/ React/Vite operator console and UI tests
apps/docs/ Astro/Starlight docs site (renders docs/, served at docs.rakkr.org)
packages/shared/ Shared TypeScript schemas / contracts
packages/db/ Drizzle schema, migrations, migration verifier
crates/recorder-agent/ Rust recorder node agent
deploy/ Ansible runner, bootstrap installer, nginx, Helm chart
docs/ Documentation source (+ internal verification baselines)
fixtures/audio/ Golden speech fixture and metadata
scripts/ Gate scripts, smokes, baseline verifiers
mise run check # full gate: docs verifiers, Drizzle replay, TS, lint, format, Cargo, Clippy, Miri, smokes
mise run build # build TypeScript packages/apps + the Rust agentSee Development and the tasks reference for targeted gates and conventions. Contributions are expected to ship as complete slices — code, tests, docs, and evidence travel together.
Built evidence-first: capture · measure · explain · recover.
The product contract and status ledger live in
docs/RAKKR_SOURCE_OF_TRUTH.md.