Installation

Nova Code ships as a Vue dashboard, Fastify API, and PostgreSQL data store. The quickest path on a machine with Docker is the install.sh helper; you can also run Compose from a git clone or install manually.

Requirements

Docker + Docker Compose (recommended), or Node.js 24 and PostgreSQL 17 for a manual install
Cursor Agent and/or Claude Code CLI on the host (or in the container image), authenticated via Settings → Agent Auth after install
Optional Mistral Vibe — install the vibe CLI on PATH, set the API key in Settings, and ensure ~/.vibe/logs/session is writable (see Sessions)
Workspace directories must be reachable by the server process (see bind mounts below)

One-line installer (`install.sh`)

The easiest way to get started. The script installs (or updates) Nova Code under ~/.novacode, generates secrets, pulls the Docker image, and starts Compose.

Prerequisites: Docker with Compose (docker compose or docker-compose) and openssl for first installs.

curl -fsSL https://raw.githubusercontent.com/JonahFintzDev/novacode/main/scripts/install.sh | bash

On first install you may be prompted to add host directory mounts for workspaces (mapped under /data-root/... in the container). After it finishes, open http://localhost:3030 and complete first-run setup in the browser.

Re-run the same command anytime to update to the latest version.

Variable	Purpose
`NOVACODE_DIR`	Install root (default: `~/.novacode`)
`NOVACODE_INSTALL_BASE_URL`	Raw GitHub URL for fetching compose and env files (for forks)
`NOVACODE_IMAGE`	Container image (default: `novacode/novacode:latest`)

Docker Compose (from a clone)

git clone https://github.com/JonahFintzDev/novacode.git
cd novacode

cp .env.example .env
# Set POSTGRES_PASSWORD, JWT_SECRET, and UID/GID as documented below.

export UID=$(id -u) GID=$(id -g)
docker compose up --build -d

Open http://localhost:3030 (or whatever you set PORT to) and complete first-run setup to create the admin account.

Key environment variables

Variable	Required	Description
`POSTGRES_PASSWORD`	Yes	Password for the PostgreSQL user
`JWT_SECRET`	Yes	Long random string for signing JWTs — generate with `openssl rand -hex 32`
`PORT`	No	HTTP port (default: `3030`)
`UID` / `GID`	No	Host user/group for container file ownership (default: `1000`)
`VIBE_COMMAND`	No	Override the Mistral Vibe executable name (default: `vibe`)
`AGENT_ENV_*`	No	Any variable prefixed with `AGENT_ENV_` is forwarded to spawned agents with the prefix stripped

Keep JWT_SECRET stable across restarts and upgrades. Changing it invalidates all browser sessions.

Manual install (without Docker)

Install PostgreSQL 17 and create a database.
Set DATABASE_URL or the individual POSTGRES_* variables (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and optional host/port).
In the API directory: install dependencies, run Prisma migrations, build, and start.
Build the dashboard and serve its dist folder via the API (production) or proxy separately (development).
Set VITE_API_URL so the dashboard can reach the API.

See the application README for exact commands and package.json scripts.

After install

First-run setup: The app shows a setup screen on first launch — create your admin account there.
Agent authentication: Go to Settings → Agent Auth and log in to Cursor and/or Claude using the embedded terminal. For Mistral Vibe, set the API key in Settings → Mistral Vibe.
Git over SSH: The server creates an ed25519 keypair on first start. Copy the public key from Settings → Git into your Git provider to enable git push over SSH.
Health check: GET /api/health returns server status without authentication — use it for Docker HEALTHCHECK or uptime monitors.
Volume mounts: The stock compose maps ~/.novacode/data to /data-root (your project files) and ~/.novacode/config to /config (app state and agent credentials). Add more bind mounts if your repos live elsewhere.