Install the tools
Use the versions pinned in .tool-versions. The repository also includes .nvmrc and .python-version for Node and Python version managers.
You will need Node.js, pnpm, and PostgreSQL for the web app. Docker Compose can supply the local database; an existing PostgreSQL server also works. Python and uv are only needed for the Python SDK and robotics checks. With nvm, load ~/.nvm/nvm.sh and run nvm install && nvm use; enable the pinned pnpm with corepack enable.
Install dependencies
From the repository root, install the web workspace:
./scripts/setup.sh web
pnpm test:installTo install both the web and Python workspaces, omit web.
Migrate and start the app
docker compose up --detach --wait postgres
export DATABASE_URL=postgresql://tinyrobot:tinyrobot@127.0.0.1:5432/tinyrobot
pnpm --filter @tinyrobot/server-cloud db:migrate
pnpm --filter @tinyrobot/server-cloud catalog:publish
pnpm devOpen http://localhost:3000. Vite watches the app and Content Collections watches the Markdown files. The Node/Start server handles the backend too; there is no separate Python API process or frontend proxy to start. Migration is explicit, not an automatic side effect of startup.
The app-only self-hosted web deployment is removed for now. An unset development BETTER_AUTH_URL defaults to http://localhost:3000; if you use a different listener port, set the matching auth origin explicitly.
The Compose credentials above are public, local-only development values. Signup and authentication methods are disabled by default; community login stays an unconfigured scaffold even when backend auth is configured. Production requires an explicit PostgreSQL URL, stable secret, and HTTPS auth origin. See the backend configuration and enrollment guide before enabling authentication or exposing an instance.
Check your changes
./scripts/format.sh web
./scripts/check.sh webKeep PostgreSQL running for the backend, HTTP and browser suites. Tests create and drop uniquely named disposable databases, not the application database. For a separate test server, set TEST_DATABASE_URL with a CREATEDB role; never use production.
The check script runs generation/drift checks, lint, formatting checks, Node tests, Vitest browser tests, Playwright E2E tests, Node website builds, and TypeScript checks. Only standalone Workers such as analytics and GitHub use Wrangler dry-runs; nothing deploys. Run pnpm test:install again after Playwright version changes; Linux machines may also need pnpm exec playwright install --with-deps chromium for browser system libraries.
Use make check for full local validation of both ecosystems, MinIO storage, the cloud Compose app/auth/migration/catalog/restart smoke, and HTTP/Query/SSE browser integration against isolated fixtures. It requires Docker and owns a disposable PostgreSQL service unless TEST_DATABASE_URL is set. Pass python to the setup/check scripts for Node-free Python checks; web checks do not require uv. There are no automatic validation or preview workflows. Railway deploys main automatically without waiting for CI, so run the full check before merging.
Next, learn where things live.