Dev Station
A desktop development workspace for agencies: switch between client projects, run their dev services,
work with AI coding agents (Claude Code, Cursor CLI) in embedded terminals, review diffs, commit and push
without juggling IDE windows. See PRODUCT.md, docs/Product_Specification.md and docs/ARCHITECTURE.md.
app/ Electron + React (Vite, Tailwind v4, shadcn/ui) desktop client
api/ NestJS + Prisma + PostgreSQL organizations, projects, integrations (Composio), sessions, activity
Requirements
- Node.js e" 22.12, Git on PATH
- PostgreSQL 14+ (local Docker works: see below)
- Optional:
claude (Claude Code) and/or cursor-agent (Cursor CLI) on PATH; cursor / code for "Open in& "
- Optional: a Composio API key for GitHub / Linear / Notion connections
Run locally
# 1. Database (any Postgres works)
docker run -d --name devstation-pg -e POSTGRES_PASSWORD=devstation -e POSTGRES_DB=devstation -p 5544:5432 postgres:16
# 2. API copy api/.env.template to api/.env.staging (or .env.local) and fill DATABASE_URL, JWT_SECRET, &
cd api
npm install
npx dotenv -e .env.staging -- npx prisma migrate deploy # applies prisma/migrations
npm run start:staging # http://localhost:3000, Swagger at /api
# 3. Desktop app app/.env: VITE_API_URL=http://localhost:3000
cd ../app
npm install
npm run dev # Vite + Electron (RENDERER_PORT=5199 npm run dev if 5173 is taken)
The API's CORS_URLS must include the renderer dev origin (e.g. http://localhost:5173). Packaged builds use the
app://devstation origin, which the API allows by default.
Build & package
cd app
npm run build # typecheck + renderer (dist/) + Electron main/preload (dist-electron/)
npm run dist # installer via electron-builder (release/); npm run dist:dir for an unpacked build
Set VITE_API_URL (e.g. in app/.env.production) before packaging it is compiled into the renderer.
cd api
npm run build && npm run start:prod # node dist/src/main
npm run migrate:prod # prisma migrate deploy with .env.production
Configuration
| Where | Variable | Purpose |
|---|
| api | DATABASE_URL, JWT_SECRET, JWT_EXPIRATION_TIME | Required |
| api | CORS_URLS, APP_URL | Allowed renderer origins (dev) |
| api | COMPOSIO_API_KEY | Enables GitHub / Linear / Notion connections |
| api | COMPOSIO_AUTH_CONFIG_GITHUB/LINEAR/NOTION | Optional: reuse existing Composio auth configs (otherwise Composio-managed ones are created) |
| api | COMPOSIO_CALLBACK_URL | Optional OAuth return URL |
| api | RESEND_API_KEY | Optional: emails invitation codes |
| app | VITE_API_URL | API base URL |
Device-only settings (workspace folder, shell, agent/editor executables, local project paths, approved custom
commands) live in the Electron user-data folder (workspace.json); the session token is encrypted with the OS
keychain (safeStorage). Nothing device-local is sent to the API.
Security model (Electron)
Context isolation + sandboxed renderer with no Node integration; a typed preload bridge is the only surface; every IPC
payload is validated with zod in the main process; filesystem paths are confined to the project root; Git runs as
git + argument arrays; service commands are built from detected package.json scripts, and any free-form command must
be approved once per device; destructive Git operations require an explicit confirmation flag; navigation and new
windows are locked to the app origin.
