Core development
Work locally
Clone the repository and use the Node.js major in .node-version and pnpm version in package.json. Start with AGENTS.md and docs/wiki/INDEX.md.
git clone https://github.com/sleepypod/core.git
cd core
pnpm install
pnpm devA development web server is not a hardware simulator. Configure disposable databases and hardware boundaries deliberately before testing write paths. Do not point an automated test at a live Pod unintentionally.
Validate a change
Use the repository’s lint, TypeScript, and relevant Vitest suites. Python modules have isolated locked environments and their own tests. For a schema change, generate migrations for the correct database.
pnpm lint
pnpm tsc
pnpm exec vitest run
pnpm buildDeploy a local build
For an already installed Pod with root SSH key access (default port 8822):
./scripts/deploy POD_IP
./scripts/deploy POD_IP fix/my-fixThe deploy helper builds locally, transfers an archive, and invokes the updater on the Pod. The updater preserves configuration, backs up code/database, installs native dependencies for the Pod, migrates, and restarts. The Pod may need temporary WAN access for dependencies; consult the deployment guide.
Never build on the Pod
Edit on your computer and deploy with ./scripts/deploy POD_IP. Do not run pnpm build or next build on the Pod.
Core releases that include core#799 refuse next build when /etc/sleepypod/data-dir exists, which is only true on an installed Pod; SP_ALLOW_POD_BUILD=1 overrides the check. On older releases, or with the override, the build runs: Next deletes the installed .next before compiling, the build runs out of the Pod’s 2GB of RAM, and the service has no .next/standalone/server.js to start. The web UI goes down until a pre-built bundle is reinstalled. See Web UI down, service restarting in a loop.
Key directories
| Path | Responsibility |
|---|---|
src/hardware/ | DAC transport, polling, locks, gestures, pump guard |
src/server/routers/ | tRPC and REST procedures |
src/scheduler/ | Scheduled temperature, power, alarms, maintenance |
src/streaming/ | WebSocket frames and MQTT bridge |
src/db/ | Configuration and biometrics schemas |
modules/ | Python sensor processors |
Source reference: Contribution instructions · Development commands · Local deployment