Self-hosted control app for Pod 3, 4, and 5. Runs on the Pod's stock embedded Linux — replaces the cloud-bound controller with a local web UI, scheduler, on-device biometrics, and opt-in integrations for Home Assistant (MQTT), Apple Home (HomeKit), and AI assistants (MCP).
Documentation lives at sleepypod.github.io. This README covers installing and working on the code; the docs site covers everything else.
No Pod? Try the live demo. It runs the real web UI against simulated Pod data in your browser, so you can change temperatures, edit schedules, and browse sleep history without hardware.
The web UI brings temperature, schedules, Autopilot, sleep, and system diagnostics into one place. Control the same Pod from the iOS app or a bedside M5 rotary dial.
Real product captures from the documentation site. The web UI capture uses disposable demo data. See asset provenance.
Live demo · Get started · User guide · Developer docs · Troubleshooting · Issues
-
Get a root shell on the Pod. Starting from a stock Pod? Follow Open your Pod and get root access — parts list, enclosure photos, Tag-Connect wiring, and serial login. You do not need to install free-sleep first.
-
Run the installer on the Pod (not on your computer):
curl -fsSL https://raw.githubusercontent.com/sleepypod/core/main/scripts/install -o /tmp/sleepypod-install less /tmp/sleepypod-install bash /tmp/sleepypod-install
-
Open
http://POD_IP:3000from a browser on the same network.
Install and update Core covers verification, sp-update, and the sp-* helper commands. The script reference documents installer flags and file locations.
Use the Node.js major in .node-version and the pnpm version pinned in package.json. Read AGENTS.md for the architecture invariants and repo conventions before changing hardware, scheduler, or database code.
pnpm install
pnpm dev # dev server on :3000 (not a hardware simulator)
pnpm test # Vitest
pnpm lint && pnpm tsc
pnpm db:generate # sleepypod.db migration from schema
pnpm db:biometrics:generate # biometrics.db migration from schema
pnpm lingui:extract # extract new user-facing strings| Variable | Default (dev) | Description |
|---|---|---|
DATABASE_URL |
file:./sleepypod.dev.db |
Path to sleepypod.db |
BIOMETRICS_DATABASE_URL |
file:./biometrics.dev.db |
Path to biometrics.db |
DAC_SOCK_PATH |
/persistent/deviceinfo/dac.sock |
Unix socket path for hardware control |
Deploy a local build to an installed Pod over SSH (port 8822):
./scripts/deploy POD_IP # current checkout
./scripts/deploy POD_IP fix/my-fix # branch from your clone's origin
./scripts/deploy --repo Kovbo/core POD_IP fix/pod3-frozen-heartbeat # fork branchSee the deployment guide for SSH requirements and fork/PR validation.
The docs site is written for people; these files track the code and change with it.
| Path | What's there |
|---|---|
docs/adr/ |
Architecture Decision Records |
docs/wiki/ |
Compiled topic briefings across the codebase |
docs/integrations.md |
HomeKit accessory map, MQTT topics, integration env vars |
docs/temperature-control.md |
Temperature arbitration between manual, schedule, and Autopilot |
docs/nats-frame-readers.md |
RAW vs NATS sensor transport selection |
docs/hardware/ |
DAC protocol, alarms, calibration, sensor profiles |
docs/trpc-api-architecture.md |
tRPC router layout and REST surface |
src/mcp/README.md |
MCP tool catalogue and design rules |
modules/ |
Python sidecars: vitals, sleep detection, calibration, environment, RAW archiving |
Next.js 16 (App Router) · React 19 · TypeScript (strict) · tRPC v11 · SQLite via better-sqlite3 + Drizzle ORM · Lingui · Vitest · pnpm · Python sidecars managed by uv · hap-nodejs (HomeKit) · mqtt.js