DEVELOPMENT DOCUMENTATION / DOWNLOADS

Install the latest development build.

Successful main CI builds produce versioned GitHub prereleases. These are development snapshots, not production-certified releases.

Choose and verify an archive

Download the archive for your operating system and CPU together with its adjacent SHA-256 file. The release tag includes the workspace version, main CI run ID and source commit. The archive's release.json records the same identity.

# Linux, from the download directory:
sha256sum -c agentuplink-*.tar.gz.sha256

# macOS, from the download directory:
shasum -a 256 -c agentuplink-*.tar.gz.sha256

Run against only the chosen archive/checksum pair. Windows users can compare Get-FileHash .\ARCHIVE.zip -Algorithm SHA256 with the downloaded .sha256 file. Stop if the values differ.

The checksum shows the download is intact, not who published it. The .sha256 file comes from the same release page as the archive. With the GitHub CLI, gh release download TAG -R andymac4182/agentuplink -p '*aarch64-apple-darwin*' fetches one target's archive and checksum.

Verify the build attestation

Releases built after the release-hardening change carry a GitHub build-provenance attestation for every archive and every .sha256 file. Verify one with the GitHub CLI, using exactly this command:

gh attestation verify ARCHIVE -R andymac4182/agentuplink --signer-workflow andymac4182/agentuplink/.github/workflows/release.yml --source-ref refs/heads/main

A pass means GitHub's Sigstore-backed signing service recorded that a file with exactly this SHA-256 was built by this repository's release workflow running on main. The commit the output names is main's tip when the release ran, which can be later than the commit the archive was built from; the source identity is sourceSha in release.json. A pass does not mean the source was reviewed or is safe, and it is not code signing: macOS and Windows still treat the binaries as unsigned. Anyone with write access to the repository's workflows can produce an attestation. Older releases have none, and the command answers HTTP 404; for those, the checksum is the only check.

Linux and macOS

The archive has no top-level folder: it unpacks LICENSE, README.txt, bin/, examples/, notices/ and release.json into the current directory; archives built after M6-C50 also carry docs/. Extract it into an empty directory.

macOS quarantine: gh release download does not quarantine files, so its binaries run as they are. An archive downloaded with a browser is quarantined and Gatekeeper refuses its binaries. After the checksum passes, and only then, remove the mark from the extracted binaries, from the extraction directory:

xattr -dr com.apple.quarantine bin

Then run these commands from that directory:

mkdir -p "$HOME/.local/bin"
install -m 755 bin/tunnel-client bin/tunnel-relay bin/tunnel-deadman "$HOME/.local/bin/"
export PATH="$HOME/.local/bin:$PATH"
tunnel-client --help
tunnel-relay --help

Add that PATH entry to your shell profile for later terminals. Keep the three binaries from the same release together: the client and supervised services need the adjacent tunnel-deadman helper.

Windows

Extract the ZIP to a permanent location, keep both .exe files (tunnel-client and tunnel-deadman) in its bin directory, and add that directory to your user PATH. Open a new terminal and run tunnel-client --help. Filesystem exports are unsupported on Windows: client configuration validation and connect refuse an fs export. A Windows binary also does not imply Unix process-group supervision or complete adapter support. The relay is not built for Windows: it runs on Linux and macOS.

Windows scope: Windows is a client-only, locked-checks target. tunnel-client credentials create and credentials import are unsupported there. A downloadable device bundle and passing compilation/tests do not establish a supported Windows enrollment workflow or M1 end-to-end acceptance.

Platform boundaries

Linux x64 builds use Ubuntu 24.04 and require compatible glibc libraries. macOS and Windows binaries are unsigned; macOS packages are not notarized. Do not disable operating-system protections globally to run a build. Review source, checksum and publisher trust before granting a local exception.

The repository also contains a single-target release-bundle verifier covering checksums, provenance, embedded licence texts, runtime assets, CLI/config probes and system-library portability. Its recorded local evidence is not a published GitHub release or certification of every download target. Packaged end-to-end operations and rotation remain separate acceptance requirements.

Configure before connecting

Archives include example configuration templates, not credentials or a running relay. Each archive also carries the operator guide, docs/operator.md, and the documents it links, written for the archive's own source commit (the CI archive's release.json; a maintainer bundle's PROVENANCE.txt). Read that copy first: this website describes reviewed main, which may be newer than your binary. A tester joining a relay someone else runs follows docs/join-relay.md in the archive, or Join a relay, instead. Continue with setup. Latest-version lookup uses the public GitHub releases API; if releases are private, view them while authenticated on GitHub instead.

Building from source

If no release is published, use an authorized source checkout and the pinned toolchain. This is the developer fallback, not the installed CLI workflow. On Linux or macOS:

cargo build --release --locked -p tunnel-client -p tunnel-relay -p tunnel-deadman --bins

On Windows, build only the device binaries:

cargo build --release --locked -p tunnel-client -p tunnel-deadman --bins

Current main does not ship a Windows relay. A manually built Windows relay exits 2 before running any command; host the relay separately on Linux or macOS.

Keep the resulting binaries together in target/release. Native dependency and runtime acceptance remains separate from compilation.