Installing the app

Everything else in Getting started assumes you are going to clone the repository and run pnpm install. This page is the other way in: one file, double-clicked, and your node is running. No Node, no pnpm, no git, no compiler.

The installer carries its own Node runtime. That is the whole idea, and it exists because the prerequisite route is genuinely fragile: the first time Novaterra was installed on a second machine — Ubuntu 20.04 with Node 20 — it failed twice over, first because there is no prebuilt better-sqlite3 binary for that Node’s ABI, and then because Ubuntu 20.04’s g++ 9.4 cannot compile the C++20 fallback. Neither question can be asked of a node that brings its own runtime.

What each platform gets today

Platform	Artefact	State
Windows 10/11, x64	`Novaterra-Setup-win-x64.exe` (~67 MB)	Built and run. Installed, upgraded in place, and driven through registration and the desktop in a browser.
Linux x64 (glibc)	`Novaterra-Setup-linux-x64.run` (~61 MB)	Built, and smoke-tested in a `ubuntu:20.04` container — the exact distribution that failed. Not yet run on a real Linux desktop: `xdg-open` and the `.desktop` entry are untested against a live session. `code.execute` has no sandbox until a Linux-built `nova-wasm` is dropped in.
macOS	—	Not built. Not tested. Nothing has ever run on macOS. The path is written down in `deploy/installers/README.md` and needs a Mac to produce and sign. Use the repository install for now.

Windows

Download Novaterra-Setup-win-x64.exe and double-click it. It installs to %LOCALAPPDATA%\Programs\Novaterra, adds a Start-menu and desktop shortcut, starts your node, opens it in your browser and shows you your access code.

No administrator, no UAC prompt: the install is per-user by choice, so it works on a locked-down machine. It also means a second Windows account installs its own copy, which for a node whose whole premise is one person’s private world is the right shape anyway.

Novaterra              start the node, or open it if it is already running
Novaterra --stop       stop the node
Novaterra --status     where it is, and whether it answers

Linux

chmod +x Novaterra-Setup-linux-x64.run
./Novaterra-Setup-linux-x64.run

It installs to ~/.local/opt/novaterra, links ~/.local/bin/novaterra, writes a .desktop entry, and starts your node. Same three commands as above.

Your access code, and why it matters

On the very first run your node generates its own secrets — a session secret, an encryption key, and an owner access code — and stores them beside its database. The access code is printed on screen, and written to FIRST-RUN.txt in your data directory. It is the only thing that can claim the owner seat.

None of these are the values in the repository’s .env.example. An install never ships with a known secret.

Where your node lives

Two directories, always, and the split is the whole upgrade story.

	Windows	Linux
The program — replaced on every upgrade	`%LOCALAPPDATA%\Programs\Novaterra`	`~/.local/opt/novaterra`
Your node — never touched by an upgrade	`%LOCALAPPDATA%\Novaterra`	`~/.local/share/novaterra` (or `$XDG_DATA_HOME/novaterra`)

Inside the second one:

data/novaterra.db          your world
data/encryption-key        wraps every stored credential and every being's private signing key
data/session-secret
data/owner-access-code
workspace/                 projects, uploads, plugins
logs/

Back up the whole data directory, not just the database. The encryption key is not a convenience: it wraps every being’s private signing key, and an identity has no reset link. Whoever holds the key is the being. Lose the key and the beings on that node cannot be recovered by anyone, including you.

To upgrade, run the newer installer. It replaces the program directory and does not touch your data — the owner code, the encryption key and every account survive, which is checked rather than assumed.

What it does not do

It opens no firewall port. Both listeners bind 127.0.0.1 only, which is also why Windows never asks you about a firewall exception. Your node is not reachable from your network until you deliberately make it so — see Self-hosting.
It phones nothing home. No telemetry, no check-in, no update ping.
It does not need Docker. code.execute runs in the WASM sandbox that ships inside the installer. Docker stays opt-in, for code that needs bash or the scientific Python stack.
It installs no service and no scheduled task. Your node runs when you start it and stops when you stop it.

Building the installer yourself

pnpm --filter @novaterra/web build
node deploy/installers/build-windows.mjs     # -> deploy/installers/out/Novaterra-Setup-win-x64.exe
node deploy/installers/build-linux.mjs       # -> deploy/installers/out/Novaterra-Setup-linux-x64.run

Windows needs a Rust toolchain (the launcher and the setup stub are Rust); Linux does not, because its launcher is a shell script. deploy/installers/README.md has the details, including what can and cannot be cross-built.