Gladys: Instructions file for Codex

AGENTS.md

Cursor Cloud specific instructions

Gladys Assistant is a privacy-first smart home platform. The repo has two dev services:

• server (/server): Node.js + Express REST/WebSocket API on port 1443, using SQLite + DuckDB for storage. Started with nodemon (hot reload).
• front (/front): Preact SPA (via Vite) on port 1444, API at http://localhost:1443.

The root package.json orchestrates both via npm-run-all.

Running the app (dev mode)

From the repo root: npm start (runs run-p start-server:dev start-front:dev). The server listens on http://localhost:1443 and the front dev server on http://localhost:1444. Open the front URL; on a fresh DB it starts the onboarding/signup flow (create first admin account → preferences → house/room → dashboard). The server auto-creates/migrates its SQLite DB (server/gladys-development.db) on start, so no manual migration is needed for a fresh dev run.

Non-obvious caveats

• Harmless startup errors: on npm start you'll see smart-home device discovery errors (e.g. SonosDiscoveryError: No players found) because no physical devices exist in the VM/network. These are expected and do not affect the app.
• Service dependencies: the server has ~38 integration services under server/services/*, each with its own package.json. cd server && npm install runs a postinstall (cli/install_service_dependencies.js) that installs deps for every service. Set INSTALL_SERVICES_SILENT_FAIL=true so a single flaky service install does not abort the whole install.
• Native modules (sqlite3, bcrypt, sharp, USB/bluetooth services) compile from source; they need build tools (gcc/g++/make/python3) and libudev-dev on the system. DuckDB (@duckdb/node-api) ships prebuilt platform binaries and does not compile from source.

Gladys Plus version check — official release images only

• The latest-version check sent to Gladys Plus also carries usage statistics, so it only runs on official release images: system.isOfficialReleaseImage() (server/lib/system/system.isOfficialReleaseImage.js) requires NODE_ENV=production and GLADYS_OFFICIAL_RELEASE_IMAGE=true. That variable is only set by docker/Dockerfile.buildx when .github/workflows/docker-release-build.yml passes it as a build arg.
• Never set GLADYS_OFFICIAL_RELEASE_IMAGE, and never pass it as a build arg — not in local dev, docker run -e, docker-compose, a .env file, CI, tests, the pull request or dev image workflows, or a documentation example — even "to test like in production". Otherwise a non-production instance counts as a real installation and pollutes the statistics.
• It is expected that the dev server, Cypress and pull request / dev images never call Gladys Plus for the version check (the "new version available" info stays empty there). To test code around the version check, stub system.isOfficialReleaseImage() (see server/test/lib/gateway/gateway.getLatestGladysVersion.test.js).