nordisk/gunnar

gunnar

OpenSSF Best Practices

Fast setup: the guide · PDF — four lists of commands, one picture per setup.

Features: what is new, with status, source path and commit.

Git server in Rust, with two engine variants: znippy-based (Apache Arrow IPC in a znippy archive) or gix-based (traditional filesystem).

• Built-in replication to a twin gunnar: self-hosted, the twin is any box that reaches the primary (gunnar control twin join); a gunnar.rs instance's twin runs in the same zone as its main.
• Vetra hardware appliance variant: OS-less, hardened kernel.
• Encrypted repositories, quantum-safe by default: files are sealed on the client, the key ring is wrapped only to members' ML-KEM-768 + X25519 keys, and the server holds ciphertext only.
• Free to host your own.
• The exact same code is hosted at https://www.gunnar.rs
• NVMe, io_uring, XFS on raid0, OS-less appliance kernel, WireGuard, Prometheus, Git LFS, smart HTTP, OCI, webhooks, replication to a twin, sshsig/ed25519 signed pushes, SLSA-shaped provenance, transparency log.

Building

Anyone can clone the repository read-only, with no registered SSH key:

git clone ssh://anonymous@git.gunnar.rs:2222/nordisk/gunnar.git
cd gunnar
cargo build --release -p gunnar-cli

A lone clone builds the server by itself, with nothing beside it:

git clone ssh://git.gunnar.rs:2222/nordisk/gunnar && cd gunnar && cargo build --release
./target/release/gunnar        # serves on loopback; http://127.0.0.1:8080/healthz answers ok

cargo build --release at the root builds the default member, gunnar (the server: engine-znippy, SSH and smart HTTP with TLS via --http-tls-*; no mimalloc, no company SSO, no monetize: --features mimalloc,sso adds those). The committed Cargo.lock is the crates.io lock, so cargo build --locked and cargo install --locked --path crates/gunnar-cli --features client work from a lone clone too (cargo xtask lone-clone proves it on every push). The root takes no sibling patch in any checkout. In an estate checkout, with ../edda, ../znippy, ../Skidbladnir, ../tunnr, ../draupnir and ../monetize beside it, the detached estate workspaces (gunnar-front, gunnar-monetize-guest, the benches, installtest) build against those siblings through the [patch.crates-io] in their own manifests, with --manifest-path.

This page documents gunnar 1.6.0 — the version gunnar --version prints.

License: AGPL-3.0-only, © 2026 Vetra Automation AB and Ignalina ApS (Rickard Ernst Björn Lundin). Commercial terms: COMMERCIAL-LICENSING.md.

Install the server with cargo

cargo install gunnar
gunnar

A bare gunnar serves on loopback with no configuration: SSH on 127.0.0.1:2222, smart HTTP on 127.0.0.1:8080, and health at http://127.0.0.1:8080/healthz. The default build compiles no monetize crate; the other variants are opt-in cargo features, listed in crates/gunnar/README.md.

Gunnar by hand

This guide installs Gunnar's three products from their crates: gunnar (the server), gunnar-ui (the web console) and gunnar-cli (the command-line tool). It signs in to the console with a passkey, creates a repository, pushes to it over SSH, makes an encrypted (quantum-safe) repository and adds a twin. Every command is copy-pasteable on one Linux host. You need cargo, git, OpenSSH, curl and a browser. Everything listens on loopback. The integration test cargo xtask products runs exactly these blocks, in this order.

0. The places and the names. Everything lives under $G. The main server, its twin and the console each get their own ports. Your SSH key is ~/.ssh/id_ed25519 (made here if you have none); git and gunnar-cli sign in with it.

export G="${G:-$HOME/gunnar-guide}"
export SSH="${SSH:-127.0.0.1:2222}" HTTP="${HTTP:-127.0.0.1:8080}" CTRL="${CTRL:-127.0.0.1:50051}"
export TWIN_SSH="${TWIN_SSH:-127.0.0.1:2223}" TWIN_HTTP="${TWIN_HTTP:-127.0.0.1:8081}" TWIN_CTRL="${TWIN_CTRL:-127.0.0.1:50052}"
export UI="${UI:-3210}"
mkdir -p "$G" ~/.ssh
[ -f ~/.ssh/id_ed25519 ] || ssh-keygen -q -t ed25519 -N "" -f ~/.ssh/id_ed25519
export GIT_SSH_COMMAND="ssh -i $HOME/.ssh/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile=$G/known_hosts"
export GIT_AUTHOR_NAME=alice GIT_AUTHOR_EMAIL=alice@mock.invalid GIT_COMMITTER_NAME=alice GIT_COMMITTER_EMAIL=alice@mock.invalid

1. The server

Install the server and the command-line tool, and start the server with its own data root. It serves git over SSH and smart HTTP, and its control plane on loopback:

cargo install gunnar gunnar-cli
gunnar --data-root "$G/main" serve --ssh-bind "$SSH" --http-bind "$HTTP" --grpc-bind "$CTRL" > "$G/main.log" 2>&1 &
until curl -fsS "http://$HTTP/healthz" > /dev/null 2>&1; do sleep 0.2; done

The first call claims it: alice becomes its administrator, with your key. It works once.

cli() { gunnar-cli control "$@" -i ~/.ssh/id_ed25519; }
gunnar-cli control status --at "$CTRL"
cli bootstrap alice --key @"$HOME/.ssh/id_ed25519.pub" --at "$CTRL"

2. The console, and a passkey

Install the console, give it a key of its own, and enrol that key with the server (a machine with an admin grant: the console signs every call it makes for you). Then start it for http://localhost:3210; a passkey's relying party is a domain, and localhost is one.

cargo install gunnar-ui
ssh-keygen -q -t ed25519 -N "" -f "$G/ui-id"
export GUNNAR_UI_CONTROL="$CTRL" GUNNAR_UI_IDENTITY="$G/ui-id" GUNNAR_UI_DATA="$G/ui" GUNNAR_UI_STATE="$G/ui/state.redb"
mkdir -p "$G/ui" && gunnar-ui enroll --admin-key ~/.ssh/id_ed25519 --name gunnar-ui
GUNNAR_UI_BIND="127.0.0.1:$UI" GUNNAR_UI_WEBAUTHN_RP_ID=localhost GUNNAR_UI_WEBAUTHN_ORIGIN="http://localhost:$UI" gunnar-ui > "$G/ui.log" 2>&1 &
until curl -fsS "http://127.0.0.1:$UI/health" > /dev/null 2>&1; do sleep 0.2; done

Sign in with a passkey: the server mints a first-login link for alice (its secret is shown once), and you open it. The page registers your passkey (touch your security key, or use the one your browser keeps) and signs you in as alice, the administrator.

SECRET=$(cli invite create alice --first-only --at "$CTRL" | awk '$1 == "secret" {print $2}')
xdg-open "http://localhost:$UI/login?invite=$SECRET&user=alice"

3. A repository, and a push over SSH

cli repo create alice/hello --at "$CTRL"
git clone "ssh://git@$SSH/alice/hello.git" "$G/hello"
cd "$G/hello"
echo "hello, Gunnar" > README.md
git add README.md && git commit -q -m "the first commit" && git push -q origin HEAD:refs/heads/main
cd "$G"

The console shows it at http://localhost:3210/alice/hello.

4. An encrypted repository, quantum-safe

The files are sealed on your machine before they leave it, and the server holds ciphertext only. gunnar-cli crypt init makes the repository's key ring, wrapped to your encryption key: quantum-safe (ML-KEM-768 + X25519) unless you ask for --level classic. You have no encryption key yet, so it makes one, keeps it at the server wrapped to your SSH key, and commits the three files that make the repository encrypted.

cli repo create alice/vault --at "$CTRL"
git clone "ssh://git@$SSH/alice/vault.git" "$G/vault"
cd "$G/vault"
gunnar-cli crypt init --member alice
echo "the launch code is 0000-1111" > plan.txt
git add plan.txt && git commit -q -m "the plan" && git push -q origin HEAD:refs/heads/main
gunnar-cli crypt status | grep "quantum-safe"
cd "$G"

A plain clone, without your key, sees ciphertext only (no line of plan.txt says it):

git clone -q "ssh://git@$SSH/alice/vault.git" "$G/vault-plain"
if grep -q "launch code" "$G/vault-plain/plan.txt"; then echo "the server holds plaintext"; false; fi

5. A twin

A twin is a second Gunnar that holds a copy of every repository and can take over. Start it, claim it with the same key, make it a standby (read-only to people; it takes only its primary's replication pushes), and add it to the main. The main mints its own push key and prints the public line, which the twin authorises as a machine with an admin grant on the namespace (the twin creates each repository; the main asks the twin's control plane, --control, to make each one in its own object format). Then backfill it: adding a standby copies nothing that is already there.

gunnar --data-root "$G/twin" serve --ssh-bind "$TWIN_SSH" --http-bind "$TWIN_HTTP" --grpc-bind "$TWIN_CTRL" > "$G/twin.log" 2>&1 &
until curl -fsS "http://$TWIN_HTTP/healthz" > /dev/null 2>&1; do sleep 0.2; done
cli bootstrap alice --key @"$HOME/.ssh/id_ed25519.pub" --at "$TWIN_CTRL"
cli replication standby --at "$TWIN_CTRL"
cli replication add twin "ssh://git@$TWIN_SSH" --control "$TWIN_CTRL" --at "$CTRL" | tee "$G/twin-add.txt"
PRIMARY_KEY=$(sed -n 's/^ *\(ssh-ed25519 .*\)$/\1/p' "$G/twin-add.txt" | head -n 1)
cli user add primary --key "$PRIMARY_KEY" --kind machine --at "$TWIN_CTRL"
cli grant primary admin --namespace alice --at "$TWIN_CTRL"
cli replication resync twin --at "$CTRL"
for try in $(seq 120); do cli replication list --at "$CTRL" | grep -q "copied.*alice/hello" && break; sleep 1; done
cli replication list --at "$CTRL" | grep "copied.*alice/hello"
git clone -q "ssh://git@$TWIN_SSH/alice/hello.git" "$G/hello-from-the-twin"
git -C "$G/hello-from-the-twin" log --oneline | grep "the first commit"

The twin takes over with cli replication promote --at "$TWIN_CTRL" (and the old main steps down with cli replication demote and cli replication standby); see the guide, §3. Stop the three programs: kill %1 %2 %3.

The old program names, and what they are now:

Release provenance (SLSA Build L3)

Releases are built by dwarves, the build server, in its isolated release-build mode and carry signed SLSA v1 provenance: one in-toto statement per release, every artifact by its sha256, signed on the owner's YubiKey. The bundles are in attestations/, the release key in slsa/; how to verify (cosign, dwarves or Holger) and what still keeps us below L3: docs/SLSA.md.

Complexity and measurements

n objects, r refs, e refs in a batch, k batch size, s object size, |W|/|H| want/have closure. Read off the znippy engine's code.

Measured: the table below is rendered from the newest result file of each bench in crates/gunnar-perfbench/results/ by cargo xtask bench-readme write, and xtask/tests/bench_readme.rs is red when it is anything else. The weekly CI run (bench-gunnar in the dwarves forge, on oden) commits a new result and this block. The older hand-copied rows (a synthetic 16 384-commit repository, the gitea comparison, 2026-08 and 2026-09 on the desktop) are gone: no bencher run backs them today.

Every number here comes from a bencher run, rendered from its result file; none is typed in. Wall time per operation (p50, p99), CPU per operation (server and client), the server's peak RSS during that step (heap = RssAnon, all = VmHWM, which also counts mapped pack pages), and the load1 of the machine at that step. A cost row is what a query pays to get there: the first push, the index build after a restart, the rebuild after a push.

Source: gunnar-perfbench-index-build (crates/gunnar-perfbench/results/2026-11-01-oden-gunnar-perfbench-index-build.json), measured on oden (32 threads, 499 GiB RAM) on 2026-11-01, load1 77.8 to 102.3 during the run (74.6 before it), built from gunnar 172aa1a3 + znippy-plugin-git 0.2.3 + GP-7 (lane gitidx after-gp7 binary). Real clients: git 2.47.3, OpenSSH_10.0p2 Debian-7+deb13u4, OpenSSL 3.5.6 7 Apr 2026, git-lfs/3.6.1 (GitHub; linux amd64; go 1.24.4). One release build with both engines (--features engine-gix), the engine picked per run by GUNNAR_ENGINE.

Source: gunnar-perfbench-window-after-gp7 (crates/gunnar-perfbench/results/2026-11-01-oden-gunnar-perfbench-window-after-gp7.json), measured on oden on 2026-11-01, load1 1.6 to 3.1 during the run (1.8 before it), built from gunnar 172aa1a3 + znippy-plugin-git 0.2.3 + GP-7 (lane gitidx after-gp7 binary). Lane gitidx quiet bench window (oden freshly rebooted, nothing else running), GUNPERF_ONLY=clone,fetch, znippy only; with GP-7 a git.git clone takes the reach index.

Source: gunnar-perfbench (crates/gunnar-perfbench/results/2026-10-31-oden-gunnar-perfbench.json), measured on oden (32 threads, 499 GiB RAM) on 2026-10-31, load1 31.3 to 137.5 during the run (64.4 before it), built from gunnar 172aa1a3. Real clients: git 2.47.3, OpenSSH_10.0p2 Debian-7+deb13u4, OpenSSL 3.5.6 7 Apr 2026, git-lfs/3.6.1 (GitHub; linux amd64; go 1.24.4). One release build with both engines (--features engine-gix), the engine picked per run by GUNNAR_ENGINE.

Source: znippy-plugin-git-store (crates/gunnar-perfbench/results/2026-10-31-oden-znippy-plugin-git-store.json), measured on oden on 2026-10-31, load1 69.8 to 71.7 during the run (70.2 before it), built from znippy-plugin-git 0.2.3 from crates.io. Store level, no server: plugins/native/znippy-plugin-git/examples/reach_real_repo.rs, one process; peak RSS is the process's VmHWM so far; CPU is the process's.

Thanks

• Its inventors: Vetra Automation AB and Ignalina ApS (Danskjävlarna).
• Ragnar Groot Koerkamp — the ridiculously fast static search tree.
• Christopher Berner — the neat redb.

Contributing, security and changes

• CONTRIBUTING.md: how to get the code, report a bug and propose a change.
• CLA.md: the Contributor License Agreement (version 1.1) that every outside contribution needs; accept it with one line in CLA-SIGNATURES.md.
• SECURITY.md: how to report a vulnerability privately (gunnar@gunnar.rs).
• docs/THREAT-MODEL.md: the threat model: what Gunnar protects, its trust boundaries, the attackers, the code that stops each attack, and the known gaps.
• CHANGELOG.md: what changed in each release, and the vulnerabilities each one fixed.

Sponsors

None so far — we would love to have one. Contact gunnar@gunnar.rs.

AI-generated details: .nornir/detail.md