gnome-jarvis/docs/operations.md

Operations guide

Prerequisites

Ubuntu GNOME 24.04 or newer, the packaged Bare runtime, PipeWire/WirePlumber, GNOME desktop portals, GTK4/libadwaita, AT-SPI2, and a QVAC-visible GPU are required for the full runtime. Node.js is a build and test dependency only. See hardware compatibility.

Web installation

For the current Gitea rolling build:

curl -fsSL https://git.ssh.surf/snxraven/gnome-jarvis/raw/branch/main/packaging/web-installer.sh | bash -s -- --enable

The installer downloads the self-contained Bare bundle from the rolling release and delegates to the repository installer. Re-running it replaces the previous user-local application and extension trees after stopping jarvisd.service; config and data stay in place. Omit --enable to copy files without starting the service unless the daemon was already running. Use JARVIS_SERVER, JARVIS_REPO, and JARVIS_BUNDLE_URL for a mirror.

Development start

npm ci
npm test
npm run gpu-doctor
npm run cu-doctor
npm run voice-doctor
bash packaging/bare-launch.sh daemon/bare-entry.js

packaging/bare-launch.sh selects the vendored Bare binary and is the same wrapper the packaged service uses. Do not reload the daemon with node --watch; Bare is the production loop.

Use npm run qvac:serve:diagnostic only when a separate local client needs the OpenAI-compatible endpoint. Keep its host at 127.0.0.1.

User service

systemctl --user daemon-reload
systemctl --user enable --now jarvisd.service
systemctl --user status jarvisd.service
journalctl --user -u jarvisd.service -f

The unit at packaging/jarvisd.service (installed to ~/.config/systemd/user/jarvisd.service) starts Bare on daemon/bare-entry.js with working directory ~/.local/share/jarvis-qvac and QVAC_CONFIG_PATH=~/.config/jarvis/qvac.config.json. The repository development unit uses the checkout path; use the packaged unit when testing installation behavior.

Restart after daemon code changes:

systemctl --user restart jarvisd.service

Desktop launcher

packaging/install.sh writes:

• ~/.local/share/applications/io.qvac.Jarvis.Control.desktop
• ~/.local/share/icons/hicolor/scalable/apps/io.qvac.Jarvis.Control.svg

The Jarvis launcher opens Control Center (gjs -m …/apps/control-center/main.js). See brand and settings.

Extension development

gnome-extensions enable [email protected]
dbus-run-session -- gnome-shell --nested --wayland

Keep inference and long-running work in jarvisd. Live HUD files are ~/.local/share/gnome-shell/extensions/[email protected]. Copy the checkout tree there, then reload the extension.

GNOME 50 does not implement ReloadExtension. Calling org.gnome.Shell.Extensions.ReloadExtension on the standalone Extensions helper can also hit a stale cache. After copying files:

1. Disable then enable on the real Shell (org.gnome.Shell at /org/gnome/Shell), or
2. Log out and back in.

A stylesheet or JS parse error (for example St CSS errcode:15) will not hot-reload until that disable/enable or a new session. See troubleshooting.

State and storage

Location	Contents	Default retention
~/.local/share/jarvis/memory	harness memory and RAG data	user-managed
~/.local/share/jarvis/voices	local voice references	user-managed
~/.local/share/jarvis/audit	CU action metadata and hashes	user-managed
~/.cache/jarvis	models, jobs, temporary CU state	disposable
~/Jarvis	generated media and transcripts	user-managed

Use the uninstall script with --yes; add --purge-data only to remove the listed Jarvis-owned data locations.