Skip to Content
DevelopersCore development

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 dev

A 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 build

Deploy 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-fix

The 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

PathResponsibility
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 

Last updated on