Skip to content
Nova Code Nova Code

FAQ

Getting started

Section titled “Getting started”

What do I need to run Nova Code?

Section titled “What do I need to run Nova Code?”

At minimum: Docker with Compose (recommended) or Node.js 24 and PostgreSQL 17 for a manual install. You also need at least one agent CLI — Cursor and/or Claude — installed and authenticated on the server. Mistral Vibe is optional. See Installation for full details.

Can I run Nova Code without Docker?

Section titled “Can I run Nova Code without Docker?”

Yes. Install Node.js 24 and PostgreSQL 17, set the required environment variables, run Prisma migrations, and start the API and dashboard. The application README has exact commands.

What is first-run setup?

Section titled “What is first-run setup?”

The first time you open Nova Code, it shows a setup screen where you create the admin account (username and password). No pre-seeding or configuration file is needed.

Workspaces & files

Section titled “Workspaces & files”

How do workspaces relate to directories?

Section titled “How do workspaces relate to directories?”

Each workspace points at a directory the server can read and write. In Docker, these are paths under /data-root (mapped from ~/.novacode/data on the host by default). The file browser and Git commands are scoped to that workspace root — they cannot access files outside it.

Can I add more directories after install?

Section titled “Can I add more directories after install?”

Yes. Add more bind mounts to the volumes section of your docker-compose.yml and restart. For example, mount /home/you/work to /data-root/work, then create workspaces with paths like work/my-project.

Agents

Section titled “Agents”

Which agents does Nova Code support?

Section titled “Which agents does Nova Code support?”

Cursor Agent, Claude Code, and optionally Mistral Vibe. The new-session UI only shows agents that are installed and authenticated on the server.

How do I authenticate agents?

Section titled “How do I authenticate agents?”

Go to Settings → Agent Auth and use the embedded terminal to log in to Cursor and/or Claude. For Mistral Vibe, install the vibe CLI on the server path and set the API key in Settings → Mistral Vibe.

Where is my code sent when I use an agent?

Section titled “Where is my code sent when I use an agent?”

Nova Code spawns agent CLIs as child processes. Those CLIs send your prompts and code context to their vendor APIs (Cursor, Anthropic, or Mistral). Nova Code does not proxy or store that traffic. See Privacy for more details.

Sessions

Section titled “Sessions”

What happens if I lose connection during a session?

Section titled “What happens if I lose connection during a session?”

WebSocket connections are used for streaming chat. If you lose connection, you can reconnect and the chat history is preserved in the database. Any in-flight response may be lost, but you can re-send the prompt.

Can I resume a session later?

Section titled “Can I resume a session later?”

Yes. Sessions persist in the database and each agent type supports resume so follow-up prompts continue the same conversation thread.

API & authentication

Section titled “API & authentication”

How do I authenticate API requests?

Section titled “How do I authenticate API requests?”

The REST API uses JWT bearer auth — the same token your browser receives after login. Send it as Authorization: Bearer <token> with your requests.

Is there a separate API key system?

Section titled “Is there a separate API key system?”

Not currently. Use the JWT from your login session for programmatic access.

What is the health endpoint?

Section titled “What is the health endpoint?”

GET /api/health returns server status (uptime and database reachability) without requiring authentication. Use it for Docker HEALTHCHECK directives or uptime monitors.

Git

Section titled “Git”

How does Git push work from Docker?

Section titled “How does Git push work from Docker?”

The server generates an ed25519 SSH keypair on first startup. Copy the public key from Settings → Git into your Git provider and use SSH remote URLs. See Files & Git for details.

Can I use HTTPS remotes?

Section titled “Can I use HTTPS remotes?”

HTTPS remotes use the host’s credential helper, not the server-generated SSH key. If your Git provider requires credentials for HTTPS, configure them on the host or use SSH instead.

Operations

Section titled “Operations”

How do I update Nova Code?

Section titled “How do I update Nova Code?”

If you used install.sh, re-run the same curl command to pull the latest image and restart. If you cloned the repo, pull the latest code and run docker compose up --build -d.

How do I back up my data?

Section titled “How do I back up my data?”

Back up your PostgreSQL database and the config volume (~/.novacode/config by default). The config volume holds agent credentials, SSH keys, VAPID keys, and MCP configuration. Your workspace files are on the host filesystem and should be included in your regular backup strategy.

What happens if I change JWT_SECRET?

Section titled “What happens if I change JWT_SECRET?”

All existing browser sessions become invalid and users must log in again. Active WebSocket connections will close. Keep JWT_SECRET stable across restarts and upgrades.

Section titled “Related”