Raven on your Linux infrastructure

Choose a build

The downloads page lists published artifacts and their requirements. The current source build adds x86_64 and ARM64 packages for glibc and musl. The pinned glibc build uses Ubuntu 22.04 and requires glibc 2.35 or newer; the musl build uses Alpine 3.23. New package formats are source build outputs until they appear in a published release.

From a source checkout with Docker installed, use the pinned builders:

python3 scripts/agent-task.py linux-build -- --libc glibc --arch x86_64 --packages
python3 scripts/agent-task.py linux-build -- --libc musl --arch aarch64 --packages

Packages include the window, daemon, CLI, local search, resources, and optional login broker. DEB, RPM, and Arch packages use glibc builds; APK uses musl. A Nix derivation in packaging/nix/raven.nix accepts an archive for the matching architecture and your pinned nixpkgs. Build and packaging details live in the repository’s Linux server guide.

Services and upgrades

Installing a package does not start or restart services. For a personal daemon, opt in with systemctl --user enable --now raven. Enable lingering if that account’s daemon should survive logout. Do not run a personal daemon and a broker-owned daemon against the same profile at the same time.

Upgrades preserve administrator configuration and leave running terminals alone. Finish or save work before an explicit service restart. Package removal leaves home profiles in place. Keep a previous package or Nix closure for rollback.

Set up per-user login

The optional raven-server broker authenticates against Linux PAM and starts a separate daemon as each allowed Unix user. The account’s UID, groups, home directory, and shell apply. Root login is refused. For the account-based hosted relay instead, use Remote hosts.

Install the broker and its root-owned, non-setuid PAM helper. Configure your distribution’s /etc/pam.d/raven policy, then copy server/server.example.json to /etc/raven/server.json and provide a TLS certificate and private key. Replace the allowlist with real users. Configuration, executables, and their parent directories must be root-owned and protected from writes by other users; keep private keys private.

{
  "mode": "login",
  "listen": "127.0.0.1:18486",
  "certificate": "/etc/raven/server.crt",
  "private_key": "/etc/raven/server.key",
  "allow_users": ["alice", "bob"],
  "runtime_directory": "/run/raven-server",
  "daemon": "/usr/lib/raven/bin/raven-muxd",
  "pam_helper": "/usr/lib/raven/bin/raven-pam"
}

This example listens on loopback. Choose the interface reachable by your clients and configure host network access before enabling the service. Run sudo raven-server --check, then explicitly enable raven-server.service. An OpenRC service is included for Alpine. Password login does not support PAM methods that require an interactive series of challenges.

Sign in and open your panes

Obtain the server’s SHA-256 certificate fingerprint through a trusted administrative channel. The startup log prints it. Supply the password on stdin, not in command arguments or shell history. Replace the password-manager command and example connection details below.

password-manager-command | raven-term remote login build-host \
  --address server.example:18486 --fingerprint SHA256_HEX \
  --user alice --password-stdin
raven-term --remote build-host api list
raven-term remote logout build-host

Login saves a connection in Raven’s private remote store. While signed in, the desktop app can attach to that name just like other saved remotes. Bearers expire after eight hours. Logout revokes the session and closes its active streams; remote remove only forgets the local saved connection. Restarting the broker invalidates all login sessions and ends its PAM sessions.

Shared accounts and Tailscale

For a shared account, configure mode: "shared", shared_user, and a private token_file with at least 32 random characters. Use Raven’s existing remote add pairing format with that token and the certificate pin. Everyone holding the token has the same authority over that account’s panes.

Embedded Tailscale is optional. Configure a hostname, private state directory, and an explicit mapping from immutable Tailscale user IDs to allowed Unix users. Enrollment happens on the server. The broker verifies the connecting peer through Tailscale WhoIs; tagged nodes, unmapped identities, and HTTP identity headers cannot grant a user login. The Unix allowlist and PAM account policy still apply.

raven-term remote login build-host \
  --address build-host:18486 --fingerprint SHA256_HEX --tailscale

TLS certificate pinning remains required inside the tailnet. Before deploying, validate your actual distribution, PAM policy, upgrade path, and tailnet access rules.