Local development in OpenSEO requires Node.js 20+, pnpm 10.30.1, and configuration of .env.local with API credentials; pnpm install --frozen-lockfile and pnpm run db:migrate:local set up the database, then pnpm dev:agents runs the dev server at http://open-seo.localhost:1355. Vite config manages the dev server's port (default 3001, overridable via PORT), exposes select environment variables to the client bundle, and permits reverse-proxy and tunnel requests via ALLOWED_HOST and BETTER_AUTH_URL. Portless is a local reverse-proxy tool that maps hostnames such as open-seo.localhost:1355 to the Vite dev server port, allowing the app to be accessed without specifying the port in the browser URL.
Local development requires Node.js 20+ and Corepack (bundled through Node.js 24; install it separately on Node.js 25+).[1] package.json declares pnpm@10.30.1 as the required package manager; run corepack enable to activate the exact declared version.[2]
The canonical local setup sequence is: corepack enable, then pnpm install --frozen-lockfile, then pnpm run db:migrate:local once per fresh local DB.[1] .env.local is configured by copying .env.example, setting DATAFORSEO_API_KEY as a base64-encoded login:password value via printf '%s' 'YOUR_LOGIN:YOUR_PASSWORD' | base64, and setting AUTH_MODE=local_noauth for normal local development.[1] Local Postgres development uses a throwaway Docker Postgres instance at postgres://openseo:openseo@localhost:5433/openseo and requires DATABASE_PROVIDER=postgres in .env.local; full details are in docs/LOCAL_POSTGRES.md.[3]
pnpm dev:agents serves the app via portless at http://open-seo.localhost:1355; in a git worktree the URL is prefixed with the branch name, e.g. http://feature-name.open-seo.localhost:1355.[1] The dev:agents script runs the dev server via portless and tees output to .logs/dev-server.log, making logs accessible to coding agents for debugging.[2] In vite.config.ts, the dev server and preview server default to port 3001, overridable via the PORT environment variable (process or .env).[4]
vite.config.ts exposes non-VITE_-prefixed env vars to the client-side bundle via envPrefix: AUTH_MODE, BYPASS_EMAIL_VERIFICATION, POSTHOG_PUBLIC_KEY, POSTHOG_HOST, and TURNSTILE_SITE_KEY.[4] vite.config.ts allows requests from hostnames derived from ALLOWED_HOST and the hostname of BETTER_AUTH_URL (if set) on both the dev and preview servers, supporting reverse-proxy and tunnel setups.[4]
Sources