Install Heimdall

Install one static x86_64 or aarch64 Linux CLI with its eBPF object embedded. Verify its checksum, authorize only the setup worker, and keep all runtime state under the invoking user.

Download and install

version=0.1.4
architecture=$(uname -m)
case "$architecture" in x86_64|aarch64) ;; *) exit 1 ;; esac
gh release download "v$version" --repo dravengarden/heimdall \
  --pattern "heimdall-egress-$version-$architecture-linux-musl.tar.gz*"
archive="heimdall-egress-$version-$architecture-linux-musl.tar.gz"
sha256sum -c "$archive.sha256"
tar -xzf "$archive"
cd "heimdall-egress-$version-$architecture-linux-musl"
sudo ./heimdall-install install
heimdall --version
heimdall init

Install through npm

npm install --global heimdall-egress
heimdall --version
npx heimdall-egress help

The npm package embeds the official x86_64 and aarch64 Linux musl binaries. It has no install lifecycle script or install-time download. Use heimdall-egress --print-native-path after a global install and authorize that exact regular binary below. An npx cache path is not a stable authorization boundary for heimdall run.

Install through PyPI

uv tool install heimdall-egress
# or: pipx install heimdall-egress
heimdall --version

# Ephemeral compatibility check only.
uvx --from heimdall-egress heimdall help

PyPI provides separate x86_64 and aarch64 Linux wheels for glibc and musl systems, with one static binary embedded in each wheel and no install-time build or download. After a persistent install, use heimdall-egress --print-native-path and authorize that exact regular binary. Do not authorize a Python launcher or ephemeral tool-cache path.

Install through Cargo

cargo install heimdall-egress --locked
heimdall --version

The crate installs only heimdall and embeds the verified eBPF object. It requires Rust 1.95 or newer, but it does not require nightly Rust or an eBPF toolchain. Authorize the exact regular path printed by command -v heimdall.

Authorize only setup

Create this entry with visudo, replacing USERNAME:

USERNAME ALL=(root) NOPASSWD: /usr/local/bin/heimdall __setup-worker

sudo chmod 0440 /etc/sudoers.d/heimdall
sudo visudo -cf /etc/sudoers.d/heimdall

Do not grant arbitrary Heimdall arguments, add file capabilities, or make the complete binary setuid.

Upgrade and rollback

sudo ./heimdall-install install
sudo /usr/local/lib/heimdall/heimdall-install verify

# Restore the previous complete executable.
sudo /usr/local/lib/heimdall/heimdall-install rollback
heimdall --version

The rollback unit includes userspace, embedded eBPF, and machine-readable contracts. It does not rewrite configuration or logs.

Keep user state unprivileged

Run heimdall init, heimdall run, and heimdall logs as the invoking user. Configuration, JSONL events, captures, and TLS CA material are user-owned. Root is used only by the hidden session setup worker.