Installing Jarela¶

Four ways to install:

All four end at the same place: a Next.js process on http://127.0.0.1:4312, with state persisted under the platform default host data dir (~/.jarela on macOS/Linux, %LOCALAPPDATA%\Jarela on Windows) or in the jarela-data volume mounted at /data.

Jarela 2.7.0 supports Node 22.22.2+ on 22.x, Node 24.15.0+ on 24.x, or Node 26+. Its release builds and bundled runtimes use Node 24.15.0, and Docker images use Node 24. Jarela 3.0.0 drops Node 22 support and requires Node 24.15.0+ on 24.x or Node 26+ for npm installations. Node 25 is not a supported release line. Native installers bundle their runtime, so no separate Node upgrade is needed.

On first launch, Jarela opens a guided setup for your profile, one model provider, a model, and your default assistant. See the first-run guide for screenshots and the first-chat personalization flow.

Path 1 — Native package¶

Download the package for your OS from the latest release:

• jarela-<version>-win.msi — Windows
• jarela-<version>-darwin.pkg — macOS
• jarela-<version>-linux.deb — Debian / Ubuntu
• jarela-<version>-linux.rpm — Fedora / RHEL-family distributions

The native packages install a pre-built Jarela bundle and a bundled Node runtime, so no separate Node install is required for this path. They are unsigned; your OS may warn you the first time you install or launch them.

After installation, run:

jarela

To register autostart for your user account:

jarela install-service

Native package install locations:

Path 2 — Pre-built archive¶

Download the archive for your OS from the latest release:

• jarela-<version>-darwin.tar.gz — macOS (arm64)
• jarela-<version>-win.zip — Windows
• jarela-<version>-linux.tar.gz — Linux

These archives are unsigned. Your OS will warn you the first time you run them. That's expected — see "First-launch warnings" below.

macOS¶

tar -xzf jarela-<version>-darwin.tar.gz
cd jarela-<version>-darwin
xattr -dr com.apple.quarantine .                     # clear Gatekeeper flag
bash scripts/install-to-system.sh --skip-build

This installs Jarela under ~/Library/Application Support/Jarela, registers a LaunchAgent so it starts at login, and opens http://127.0.0.1:4312 once it's up.

Windows¶

Expand-Archive jarela-<version>-win.zip
cd jarela-<version>-win
powershell -ExecutionPolicy Bypass -File scripts\install-to-system.ps1 -SkipBuild

This installs Jarela under %LOCALAPPDATA%\Programs\Jarela, registers a Scheduled Task to start it at logon, and opens http://127.0.0.1:4312.

If SmartScreen blocks the script: More info → Run anyway.

Linux¶

tar -xzf jarela-<version>-linux.tar.gz
cd jarela-<version>-linux
bash scripts/install-to-system.sh --skip-build

(There is no LaunchAgent / Scheduled Task on Linux — the install script lays the bundle down, you choose your own supervisor: systemd --user, nohup, etc.)

First-launch warnings¶

• macOS "unidentified developer": the xattr -dr com.apple.quarantine line above clears it for the whole bundle in one go. Without it, you'd right-click → Open the first time per binary.
• Windows SmartScreen: More info → Run anyway, once.

These warnings exist because we don't yet pay for an Apple Developer ID or an Authenticode cert. See ADR-0011 for the trade-off.

Path 3 — npm (recommended)¶

npm install -g @circuitwall/jarela
jarela

The published npm package ships a prebuilt standalone bundle, so jarela starts immediately after install — no in-place webpack/build step.

On the very first interactive jarela run, you'll be offered to register autostart for the current user:

Jarela isn't registered as an autostart service yet.
Install autostart now so it runs at login? [Y/n]

Answer Y and Jarela installs the native autostart entry for your OS (see table below), starts it in the background, and exits the foreground. Answer n and jarela keeps running in the foreground; you can register later with jarela install-service. The prompt is silent in non-TTY shells (CI, pipes, Dockerfiles) and under sudo, and can be permanently disabled with JARELA_NO_FIRST_RUN_PROMPT=1.

To run on a non-default port:

PORT=4400 jarela

To upgrade:

npm update -g @circuitwall/jarela        # or: jarela update
jarela --version                          # confirm the installed version
jarela                                    # uses the prebuilt bundle

Install as an autostart service (non-interactive)¶

If you skipped the first-run prompt, or you're scripting the install:

jarela install-service        # auto-detects Windows / macOS / Linux

This registers the native autostart mechanism for your OS, points it at the global jarela binary, and starts it immediately:

Linux note: the unit is installed in user scope. To keep Jarela running after you log out, also run loginctl enable-linger $(whoami) once.

To remove:

jarela uninstall-service

(Neither command touches your data dir.)

Path 4 — Docker (Ubuntu / Linux)¶

A Dockerfile and docker-compose.yml ship at the repo root. The image is based on node:24-trixie-slim (Debian 13) and runs as a non-root user.

Quick start (docker compose)¶

git clone <repo-url> jarela
cd jarela
docker compose up -d --build
# open http://127.0.0.1:4312

From Docker Hub (no clone, no build)¶

Releases tagged v* publish a multi-arch (linux/amd64 + linux/arm64) image to Docker Hub at andrewgewu/jarela:

docker run -d --name jarela \
  -p 127.0.0.1:4312:4312 \
  -v jarela-data:/data \
  --restart unless-stopped \
  andrewgewu/jarela:latest

Pin to a specific version with andrewgewu/jarela:0.1.0 (or the major/minor tags andrewgewu/jarela:0.1, andrewgewu/jarela:0).

State (SQLite, encrypted secrets, uploads) is persisted in the named jarela-data volume. To reset, docker compose down -v.

Quick start (plain docker)¶

docker build -t jarela .
docker run -d --name jarela \
  -p 127.0.0.1:4312:4312 \
  -v jarela-data:/data \
  --restart unless-stopped \
  jarela

Or bind-mount a host directory instead of a named volume:

mkdir -p ~/.jarela
docker run -d --name jarela \
  -p 127.0.0.1:4312:4312 \
  -v ~/.jarela:/data \
  jarela

Container notes¶

• PORT defaults to 4312, HOSTNAME to 0.0.0.0 (so the published port is reachable on the host). Override either with -e PORT=… -e HOSTNAME=….
• JARELA_DB_DIR is set to /data — mount a volume there to persist.
• No D-Bus / OS keychain is available inside the container, so the master encryption key transparently falls back to a 0600-permissioned file at /data/.secret-key (see ADR-0005). Back up /data to back up everything.
• LAN exposure: drop the 127.0.0.1: prefix in the port mapping (-p 4312:4312) — but the app has no built-in auth, so only do that on a trusted network.

Upgrade¶

git pull
docker compose up -d --build

The jarela-data volume survives rebuilds.

Uninstall¶

docker compose down            # keep data
docker compose down -v         # wipe data too

Where state lives¶

All persistent state — chat threads, model configs, integration tokens, scheduled tasks — lives under:

• macOS / Linux: ~/.jarela/
• Windows: %LOCALAPPDATA%\Jarela\

Override with JARELA_DB_DIR=/path/to/dir. Uninstalling does not delete this directory; remove it by hand if you want a clean slate.

Jarela Local embedding model¶

The on-device embedding model (about 136 MB) is not part of the installers. The first time you select Jarela Local under Settings → Models → Embeddings, Jarela downloads it from Hugging Face. The download is pinned to a fixed revision, every file is hash-checked, and the model is stored in models/local-embedding/ under the data directory above. For offline or air-gapped machines, build with JARELA_BUNDLE_LOCAL_EMBEDDING=1 to include the model in the bundle. Set JARELA_LOCAL_EMBEDDING_DOWNLOAD=0 to stop Jarela from ever downloading it.

Back up and restore¶

jarela backup ~/jarela-backup-2025-01-01   # folder must be new or empty

jarela backup reads JARELA_DB_DIR (or the default location above) and writes a consistent snapshot that is safe to take while Jarela is running: - jarela.db and checkpoints.db (captured with SQLite VACUUM INTO); - the files/, providers/, tools/, and packages/ folders; - a jarela-backup.json manifest.

It never copies the master key (.secret-key / .secret-key.enc / OS keychain entry), messaging-bridge sessions (baileys/), the re-downloadable embedding model, or logs. Saved credentials stay encrypted in the snapshot.

To restore: 1. Stop Jarela. 2. Copy the backup's contents into an empty data directory, without the manifest. 3. Start Jarela again.

On the same machine (same keychain or keyfile), credentials keep working. On a machine without the original master key, the encrypted credentials cannot be decrypted, so re-enter them in Settings. In every case, re-pair any messaging bridges.

Uninstall¶

• macOS: launchctl unload ~/Library/LaunchAgents/com.jarela.app.plist && rm -rf ~/Library/Application\ Support/Jarela ~/Library/LaunchAgents/com.jarela.app.plist
• Windows: powershell -ExecutionPolicy Bypass -File scripts\uninstall-from-system.ps1
• npm (CLI only): npm uninstall -g @circuitwall/jarela
• npm (with autostart service): jarela uninstall-service && npm uninstall -g @circuitwall/jarela