Installation

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

Requirements

Docker + Docker Compose (recommended), or Node.js (see the app repo for the supported version) and PostgreSQL
Cursor Agent and/or Claude Code CLI on the host (or in the container image), authenticated via Settings → Agent Auth in the app
Workspace directories must be reachable by the server process (see bind mounts / data-root in the app docs)

One-line installer (`install.sh`)

The application repository includes scripts/install.sh: it installs or updates NovaCode under ~/.novacode (override with NOVACODE_DIR), writes a generated .env with secrets, pulls the published image, and starts Compose. If ~/.novacode/.env already exists, re-running the script performs an update (refresh compose, pull images, recreate containers).

Prerequisites: Docker and Compose (docker compose or docker-compose), and openssl for fresh installs.

From any directory:

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

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

Variable	Purpose
`NOVACODE_DIR`	Install root (default: `~/.novacode`)
`NOVACODE_INSTALL_BASE_URL`	Raw URL of the repository root on GitHub (no trailing slash) — used to fetch `scripts/docker-compose.install.yml` and `.env.example`. Defaults to the upstream app repo; set to your fork’s raw URL, e.g. `https://raw.githubusercontent.com/YOU/novacode/main`
`NOVACODE_IMAGE`	Container image (default in script: `novacode/novacode:latest`)

Re-run the same curl | bash command anytime to update. See the script header comment in the repo for the full behavior.

Docker Compose (clone repo)

From the repository root (contains docker-compose.yml and .env.example):

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

cp .env.example .env
# Set POSTGRES_PASSWORD, JWT_SECRET, and UID/GID as documented in the app README.

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

Open the URL printed by Compose (commonly http://localhost:3030 depending on PORT). Complete first-run setup in the browser to create the admin user.

Manual install (outline)

Install PostgreSQL and create a database.
Set DATABASE_URL or POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, and optional host/port (see API env resolution).
In the API package: install dependencies, run Prisma migrations, build, start the server.
Build the dashboard and either serve its dist via the API in production or proxy it separately.
Configure VITE_API_URL (or equivalent) so the dashboard points at your API.

Exact commands match the application README and package.json scripts—this site stays in sync conceptually; verify versions there before production.

After install

Authentication: JWT after setup/login; change password or username under Account.
Health: GET /api/health for monitoring (no auth).
Agents: Log in to Cursor/Claude from Settings using the embedded terminal flows when needed.
Git over SSH: The server creates an SSH keypair on the config volume on first run. Use Settings → Git to copy the public key into your Git provider if you need git push over SSH from the container.