Install

The installer supports Linux on Debian or Ubuntu (apt). Run it as root or through sudo; it also needs curl. Elowen requires Node.js 22.19 or newer, and the installer installs it when the host has none or an older one. Git is needed for Git Projects and worktrees. ripgrep powers file search and Linux Sandbox execution needs bubblewrap; the installer installs both when they are missing.

Install the release

Install Elowen. The installer asks for your licence key in a masked prompt:

curl -fsSL https://<licence-server>/hooks/licensing/v1/install.sh | bash

It verifies the key before changing the host, downloads the licensed release, and then provisions the supervised services and runs the setup wizard in the same run. The wizard configures the first administrator, an optional Project, the AI provider and model, your preferences, and optional memory embeddings and language-server support. When it finishes it prints the Web UI address; elowen opens the terminal chat.

For an unattended install, let your secrets store set ELOWEN_LICENCE_KEY in the environment and pass ELOWEN_INSTALL_ARGS='--unattended …'. Never put the key on the command line, inline KEY=value included: it leaks into shell history and process lists. To configure a machine later, or from flags, run elowen setup --non-interactive with the required options shown by elowen setup --help.

If the installation has no usable licence yet, activate afterwards with elowen licence activate (key from ELOWEN_LICENCE_KEY or a prompt, never a command argument) or enter the key on the web app's licence page. Details: Licence.

To review the installer before running it, download it first instead of piping it directly into bash:

curl -fsSL https://<licence-server>/hooks/licensing/v1/install.sh -o install.sh
less install.sh
bash install.sh

It is the same script as the one-liner above; downloading it first only changes when you read it.

The installer verifies the release download, prepares native build tools, and installs exactly the reviewed production lock with npm ci. It keeps releases in versioned directories and switches the command link atomically. The package is committed only after the provisioner's checks pass.

A globally linked developer checkout (created with npm link) is never replaced, and ELOWEN_FORCE does not override that. The installer stops and tells you to update the checkout in place instead.

If Elowen is already installed on the machine, the installer asks before it reinstalls and re-provisions the instance. Answering no leaves the existing installation untouched; update it with elowen update. Without a terminal the installer refuses. Set ELOWEN_FORCE=1 to reinstall without the question, for example in automation.

Install supervised services

The command above already does this. On a host where the package is installed but the services are not provisioned yet, for example a source checkout, run it directly:

sudo elowen install

It configures the service user, reverse proxy, HTTPS, and required runtime tools, then starts the setup wizard. Use elowen install --help to review deployment options before accepting system changes. For unattended installation, pass --unattended and the required options explicitly.

A local install also provisions PostgreSQL 18 and its own PgBouncer on the host. To use an external database instead, pass --database-url: the server must run PostgreSQL 16 or newer, have the vector (0.7 or newer) and pg_trgm extensions installed in the database, list pg_stat_statements in shared_preload_libraries, and give its role schema-creation rights. A URL that reaches the database over TCP must carry sslmode=verify-full.

Connect computers with the Elowen CLI

The installer sets up the server. A Linux, macOS or Windows computer that Elowen should work on is connected from the web app instead: open Account > Computers on that computer and choose Copy install command. On Windows the command runs in PowerShell and needs Windows 10 22H2 or Windows 11; inside WSL, use the Linux command. Details: CLI.

Build from a source checkout

The core repository is private; a licensed release comes from the licensing server as described above, not from a public clone. If your organization has its own checkout of the source, build it with:

npm ci
npm ci --prefix web
npm run build
npm run build:web

npm run build builds the daemon and bundled plugin assets. npm run build:web builds the Web UI server. On a supervised source checkout, reinstall the root-owned files from the new build; until they match the code, the daemon refuses privileged requests:

sudo elowen privileged refresh

Source core code still updates from git and a rebuild. Publisher plugins can be installed, updated and repaired through the normal marketplace without replacing the source core.

Install a plugin

Open Settings → Available plugins and choose Install on a plugin; review any requested permissions. Declining that question changes no plugin files. After acceptance, the plugin says Queued while Elowen prepares its files, restarts the affected services and checks startup. Wait for Applied before using its tools. A plugin that stays disabled goes through the same queue and restart, but Elowen does not require it to load at startup.

If startup fails, Elowen rolls the change back and shows the reason. An installed plugin that could not load stays in the list under Settings → Plugins with Not loaded and a Repair action. See Production & Updates for progress and recovery.

Manage services

elowen up
elowen down
elowen down --force
elowen status
elowen restart daemon
elowen restart web
elowen restart all
elowen update
elowen doctor

A normal stop checkpoints running turns. --force interrupts them.

Next: Docker