Skip to content

Advanced

Linux and other machines

A Linux computer or server becomes a body with one curl command: dependencies are installed, a service that starts at boot and restarts after a crash is registered, Quetzal appears in your app list, and the web console opens in your browser; any other machine with Node.js 22.13+ and git can be set up by hand.

#When this applies

A phone is the best body, but a laptop, a small home server, a Raspberry Pi or a cloud VM can run the runtime too. Linux machines have a one-line installer (this page). Windows PCs are covered in Windows. Macs use the same command as Linux; see macOS. Other systems follow section 4 by hand.

#1. Linux: one command

bash
curl -fsSL https://quetzal.plutokeating.beer/install | bash

You need Linux, curl (or wget) and bash 4+. The script installs anything else that is missing.

On x86_64 and arm64 you get everything, native console included. Architectures without official Node binaries, such as LoongArch (loongarch64), RISC-V and armv6l, get the matching Node 22 from the Node.js project's unofficial-builds in ~/.quetzal/node/. The script checks it against SHASUMS256.txt from the same release directory first (there are no GPG signatures there). The runtime and the web console then work as usual, but there is no native console (upstream Flutter does not support LoongArch yet), and the app-list entry opens the browser.

Afterwards:

  • The web console http://127.0.0.1:7788/ is open in your browser, logged in without a pairing code on the same machine; models, identity, permissions, Feishu, the soul repository and conversations all live there (section 2).
  • Your app list has a Quetzal entry (the orb icon) that opens the native console (the Flutter Linux desktop build, downloaded from the GitHub Release of the same version into ~/.quetzal/console/); the taskbar, Alt-Tab and the activities overview show Quetzal's own icon. When no native package exists for this version (arm64, older releases) or the download fails, it falls back to the browser: Chromium-family browsers open it as a separate window, Firefox opens it in the default browser, and the taskbar then shows the browser's icon.
  • The terminal has a quetzal command (~/.local/bin/quetzal, available in new terminals): quetzal status / logs -f / open / rollback / uninstall.
  • It starts by itself at boot and comes back within 3 seconds after a crash or kill; running the same command again upgrades.

What the installer does, step by step (idempotent):

StepWhat happens
This machineDetects the distribution, architecture, package manager (apt / dnf / yum / pacman / zypper / apk / xbps), whether a systemd user instance exists, whether there is a desktop, WSL / container
DependenciesInstalls git, curl, tar and CA certificates with the machine's own package manager when missing (sudo / doas asks for a password once if needed; root installs directly). Node.js 22.13+: a new enough one on PATH (with npm) is used as is; otherwise nvm goes into ~/.nvm and installs Node.js 22 (the system Node is untouched; nvm's install script is downloaded to a file and only run when it matches the SHA-256 pinned in the installer, and both download locations serve identical content). musl systems such as Alpine and NixOS cannot run nvm's official binaries: Alpine gets apk add nodejs npm, NixOS needs Node provided beforehand. If nodejs.org is unreachable the mainland-China mirror (npmmirror) is used automatically
RuntimeInstalls the npm package @plutokeating/quetzal into ~/.quetzal/npm (its own prefix, nothing global), which places the version directory, default configuration, systemd service, health check and rollback (see 1.1)
SupervisionWith a systemd user instance: the systemd --user service quetzal, Restart=always, plus loginctl enable-linger so it runs without a login session (asks for a password once if administrator rights are needed). Without one (Alpine / Void / Devuan, containers, WSL without systemd): a small supervisor loop ~/.quetzal/bin/quetzal-supervise (restarts 3 s after any exit, flock keeps it single), started at boot via crontab @reboot and a desktop autostart entry; no extra service framework is installed
DesktopOnly with a desktop environment: downloads the native console of the same version into ~/.quetzal/console/<version>/ (first it verifies the release signature: SHA256SUMS.sig must be a valid Ed25519 signature by the embedded public key, the commit <commit> v<version> line must name the version being installed, and the tarball's SHA-256 must match the manifest; if any check fails, or the release is too old to have a signed manifest, it falls back to the browser, see Release signatures and verification. console/current points at it; the dependency check only reads the binary with readelf -d/-V or objdump -p (required libraries and glibc version) and never runs it, and is skipped when neither tool exists; on old distributions with missing libraries it gives up and falls back to the browser; musl systems never get the native console), icons into ~/.local/share/icons/hicolor/ (xyz.quetzal.console.png), the launcher ~/.local/bin/quetzal-console (native first, browser otherwise), and ~/.local/share/applications/xyz.quetzal.console.desktop
FinishOpens the console when there is a graphical session; prints the address, the supervision mode and the common commands. On a server it prints ssh -L 7788:127.0.0.1:7788 <this machine>

Options go after bash -s --; each has an environment variable too:

OptionEnvironment variableEffect
--lanQUETZAL_LAN=1Open the gateway to the LAN so the phone app can connect to this machine directly (encrypted HTTPS on port 7789 only; plain HTTP stays on this machine)
--no-openQUETZAL_NO_OPEN=1Do not open the browser afterwards
--no-desktopQUETZAL_NO_DESKTOP=1Skip the app-list shortcut
--home DIRQUETZAL_HOME=DIRHome directory (default ~/.quetzal; installs made before 0.6.7 under ~/quetzal are moved to ~/.quetzal automatically the next time the installer runs, keeping configuration, memories and conversations)
--version X.Y.ZQUETZAL_VERSION=X.Y.ZInstall a specific version (default latest)
--cn / --no-cnQUETZAL_MIRROR=cn / offForce the mainland-China mirror on / off (auto-detected by default)
--lang zh / enQUETZAL_LANG=zh / enInterface language (default follows the system locale: Simplified / Traditional Chinese show Chinese, anything else English)
--uninstall [--purge]—Remove the service, supervisor loop, shortcuts and npm package; --purge also deletes ~/.quetzal (configuration, memories, conversations). nvm, Node.js and git stay
bash
curl -fsSL https://quetzal.plutokeating.beer/install | bash -s -- --lan        # with options
curl -fsSL https://quetzal.plutokeating.beer/install | bash -s -- --uninstall  # uninstall

The script's source is cli/install.sh in the repository; the website build copies it verbatim to /install, and it is also available at https://raw.githubusercontent.com/PlutoKeating/Project.Quetzal/main/cli/install.sh. The install log is ~/.quetzal/install.log.

The service uses the absolute path of the Node chosen at install time (for nvm that is ~/.nvm/versions/node/v22.x/bin/node), so nvm uninstall 22 later breaks the service; rerunning the install command fixes it. On machines without systemd the quetzal stop / logs subcommands do not apply: stop with kill $(cat ~/.quetzal/state/supervise.pid), and the log is ~/.quetzal/logs/runtime.log.

#Command sandbox

The commands it runs (shell, custom tools) run in a sandbox and cannot see the runtime's secrets (model keys, tokens, deploy keys). The install script prepares one in this order:

  1. bubblewrap, installed with the machine's package manager (every major distribution has it).
  2. Ubuntu 23.10 and later restrict "unprivileged user namespaces" with AppArmor by default, so bubblewrap cannot create a sandbox. The script asks for your administrator password once and installs a Quetzal-only copy of bubblewrap with an AppArmor profile that applies only to it (/usr/local/lib/quetzal/bwrap, /etc/apparmor.d/quetzal-bwrap); the system bubblewrap and this system protection are left alone, and both are removed on uninstall.
  3. Still not possible (the kernel forbids it, or inside a container): the kernel's own Landlock is used instead, through the landrun launcher downloaded and verified against the release signature; no administrator rights needed.
  4. Otherwise: proot on Debian / Ubuntu (best-effort isolation).

When none is available the runtime refuses to run its commands, so they cannot read the secrets; the console's Control → Advanced → Runtime page explains why. Add a sandbox and rerun the install command. You can also turn on running without isolation on that page (unsafe).

#1.1 Just the npm package: npx @plutokeating/quetzal

If you already have Node.js 22.13+ (node:sqlite needs no flag from this version on) and git, and do not want a desktop shortcut, the npm package alone is enough; the one-line installer calls it internally.

bash
npx @plutokeating/quetzal            # install: the runtime, the Linux body adapter and the web console go into ~/.quetzal, a systemd user service is registered and started, then the console opens in the browser
npx @plutokeating/quetzal open       # open the web console again, http://127.0.0.1:7788/
npx @plutokeating/quetzal --lan      # also open the gateway to the LAN (encrypted HTTPS, port 7789) so the app on your phone can connect to this machine directly

What it does: it copies the bundled main.cjs, linux.mjs and the web console web/ into ~/.quetzal/releases/<version>/ and points current at it (the same directory convention as on the phone); writes ~/.config/systemd/user/quetzal.service (restart on exit), starts it and waits for /health; if there is no response within 40 seconds it switches back to the previous version. On a first install with a desktop it opens the browser (--no-open to skip). Running npx @plutokeating/quetzal again upgrades.

Common commands (after the one-line install, npx @plutokeating/quetzal can be replaced by quetzal):

CommandEffect
npx @plutokeating/quetzal statusVersion, service, health, gateway and web console addresses
npx @plutokeating/quetzal openOpen the web console in the browser
npx @plutokeating/quetzal logs -fService log (journald)
npx @plutokeating/quetzal rollbackSwitch back to the previous version and restart
npx @plutokeating/quetzal stop / start / restartService control
npx @plutokeating/quetzal uninstall [--purge]Remove the service; --purge also deletes ~/.quetzal (configuration, memories, conversations)
npx @plutokeating/quetzal runNo systemd user instance (containers, WSL without systemd): run in the foreground under your own supervisor

The service uses the Node that ran npx at install time, so a Node installed by nvm or similar works too; the service does not depend on the npx cache. Running without a login session (servers) needs loginctl enable-linger; the installer tries it and tells you to run it once with sudo if it fails.

#What this body can sense

The Linux adapter detects what the machine has. A laptop reports battery level and charging, and CPU temperature goes into extra. With a desktop session it can show notifications, play sound, see and operate the screen (see Operating the screen), read the clipboard and open URLs. With a camera and microphone it can take photos and record. On a headless server those tools report that they are unavailable. Details in Adapter interface.

#2. The web console: usable as soon as it is installed, no phone needed

Open http://127.0.0.1:7788/. This is the Quetzal app as a web page, laid out for a wide screen: navigation (chat / flow / memory / control) and the current section's list on the left, what you are reading in the middle, and on the right, always, how it is right now (the orb, the thought it wants to share, a wake in progress, requests waiting for your approval, its inner state and body). Models, identity, permissions, Feishu, the soul repository and conversations all work here as in the app.

  • No pairing code: a browser on the same machine is logged in as soon as the page opens (the gateway only accepts requests from the loopback address with a local Host header; see Gateway API).
  • Headless server: forward the port with ssh -L 7788:127.0.0.1:7788 <server> and open the same address in your local browser; a tunnelled connection counts as local to the gateway.
  • The address bar records where you are (#/chat/<session>, #/control/providers, …): bookmarkable, back and forward work.
  • The web version has no microphone and no installer: hearing lives in the phone app; to upgrade, rerun the install command (or npx @plutokeating/quetzal) on this machine.

#3. Connect the phone app to a Linux machine (optional)

  • Installed with --lan: in the app, top-bar name → Connect another (or expand Connect another device on the connection page) → enter just this machine's address (e.g. 192.168.1.8; the app uses the encrypted https://192.168.1.8:7789 automatically) → the app shows this machine's certificate fingerprint; check that it matches what npx @plutokeating/quetzal status prints → Get pairing code.
  • Without it: the gateway listens on 127.0.0.1 only, so forward the port first (adb reverse tcp:7788 tcp:7788 with the phone attached over USB, or an ssh tunnel) and enter 127.0.0.1:7788 in the app. You can switch to open at any time with npx @plutokeating/quetzal --lan.

The pairing code, together with the certificate's short fingerprint (e.g. 配对码 ABCD-EFGH · 证书指纹 1a2b 3c4d 5e6f 7a8b), appears as a desktop notification on that machine and is written to the service log; on a headless server read it from quetzal logs.

Everything on the LAN is TLS-encrypted; plain HTTP stays on this machine's 127.0.0.1:7788. The certificate is generated by the runtime itself (self-signed); the app records its fingerprint when pairing and from then on accepts only that certificate. The pairing code is only used in a computation inside the app and never travels over the network, so someone in the middle impersonating this machine cannot pair. Opening https://<this machine's address>:7789/ in a browser on another computer shows an "untrusted certificate" warning: view the certificate and continue only if the start of its SHA-256 fingerprint matches the short fingerprint in the notification. Connections saved by older app versions as http://<address>:7788 show "运行基座已改为加密连接,请重新配对" (the runtime now requires an encrypted connection; pair again).

#4. Other machines: manual deployment

Any machine with Node.js 22.13+ and git can be a body.

bash
git clone https://github.com/PlutoKeating/Project.Quetzal.git
cd Project.Quetzal/runtime
npm ci
npm test            # unit tests
npm run build       # produces dist/main.cjs (single file, dependencies bundled) and the platform adapters dist/android.mjs, dist/linux.mjs, dist/termux.mjs, dist/windows.mjs
QUETZAL_HOME=~/.quetzal node --enable-source-maps dist/main.cjs

Environment variables:

VariableMeaning
QUETZAL_HOMEHome directory (default ~/.quetzal): configuration, secrets, data and the soul directory
QUETZAL_ADAPTERPath to a body adapter module; unset means the generic adapter (OS information only, no sensors)

Process supervision is external: when the runtime exits, something else has to restart it. For example, a systemd user service:

ini
[Unit]
Description=Quetzal runtime

[Service]
Environment=QUETZAL_HOME=%h/quetzal
Environment=QUETZAL_ADAPTER=/path/to/your-adapter.mjs
ExecStart=/usr/bin/node --enable-source-maps /opt/quetzal/main.cjs
Restart=always

[Install]
WantedBy=default.target

More than five starts within ten minutes puts the runtime into safe mode (gateway and Feishu only, no waking) so a crash loop cannot burn money.

Connecting works as in section 3 (a manual deployment has no web console unless you place the console's web build next to main.cjs as web/ or point QUETZAL_WEB_DIR at it); to open the gateway to the LAN set gateway.lan to true (or gateway.host to 0.0.0.0) in config/quetzal.json: HTTPS / WSS opens on the LAN (gateway.lanPort, default 7789) while plain HTTP stays on this machine. Adapters without notify (such as the generic one) cannot show the pairing code; in that case read the token from QUETZAL_HOME/secrets/gateway.token and enter it directly.

The generic adapter has no sensors. A few dozen lines of code give this machine its own adapter, so the agent can feel its body and use device tools. See Custom body adapter.

#Development mode

bash
cd runtime && npm run dev     # run the TypeScript sources directly with ./.dev as home
cd cli && npm run build && node dist/quetzal.mjs status --home /tmp/w   # build the npm package and try it with a separate home