Versioning and install

Install from a release

Each release carries both binaries, the control-plane image, and what is needed to check that they came from the release workflow at that release's tag:

<version> is the tag without its v: release v0.4.1 carries innerwall-agent_0.4.1_linux_amd64.tar.gz and the image ghcr.io/innerwall-dev/innerwall:0.4.1. Each archive holds the binary and LICENSE. Images are tagged by version only; nothing is tagged latest.

Signing is keyless. No signing key exists to leak: the certificate names the release workflow, at the tag, as the signer, and the signature is recorded in the public transparency log. Verifying takes two checks. The signature proves checksums.txt came from that workflow at that tag, and the checksum proves the archive is the one the file lists.

Download, verify, install

Set the release and the asset (for the control plane, innerwall_${VERSION}_<os>_<arch>.tar.gz), and download it with the checksum file, its signature, and its certificate:

VERSION=0.4.1
ASSET=innerwall-agent_${VERSION}_linux_amd64.tar.gz
base=https://github.com/innerwall-dev/innerwall/releases/download/v$VERSION
for f in "$ASSET" checksums.txt checksums.txt.sig checksums.txt.pem; do curl -fsSLO "$base/$f"; done

Verify the checksum file's signature with cosign 2.x. It prints Verified OK only for a signature by the release workflow at v$VERSION; any other signer, or any other tag, fails:

cosign verify-blob checksums.txt --signature checksums.txt.sig --certificate checksums.txt.pem \
  --certificate-identity "https://github.com/innerwall-dev/innerwall/.github/workflows/release.yml@refs/tags/v$VERSION" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Check the archive against it. This prints the asset's name and OK; on macOS use shasum -a 256 -c in place of sha256sum -c:

awk -v f="$ASSET" '$2 == f' checksums.txt | sha256sum -c

Install the binary:

tar -xzf "$ASSET"
sudo install -m 0755 innerwall-agent /usr/local/bin/innerwall-agent    # the control plane: innerwall

A host without cosign can be served by a machine that has it: verify there, copy the archive and checksums.txt to the host, and repeat the checksum line on the host.

The image. The quickstart runs it with Docker Compose by naming it in .env as INNERWALL_IMAGE. The image is signed by the same workflow, by digest; to verify it before running it:

cosign verify ghcr.io/innerwall-dev/innerwall:0.4.1 \
  --certificate-identity https://github.com/innerwall-dev/innerwall/.github/workflows/release.yml@refs/tags/v0.4.1 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

What the binaries do not do. Neither binary checks for updates or sends telemetry. The control plane opens no connection except to its Postgres; the agent dials only the control-plane address it is given. Nothing updates itself either (ADR-0011): an upgrade is always an operator replacing a binary or an image (upgrading).

The agent runs on Linux only, as root, with nftables. Running the control plane is in the quickstart and docs/deploy/README.md; placing agents on other machines is in multi-host evaluation.

Fallback: build from source

Build from source when no release asset fits: another architecture, an unreleased commit, or a tree with changes. Building needs Go (the version go.mod names) and, for the console, Node 22:

git clone https://github.com/innerwall-dev/innerwall.git
cd innerwall
git checkout v0.4.1   # the release to build; without it, the build is of main
make console    # builds the console into ui/dist/
make build      # bin/innerwall and bin/innerwall-agent, the console embedded

make build-noconsole builds both binaries without Node; that control plane serves the API and no console. Both binaries are static (CGO_ENABLED=0), so the agent can be built for another Linux architecture on the build machine and copied to the host:

CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -o bin/linux-arm64/ ./cmd/innerwall-agent

make dev is the same fallback for the Docker Compose stack: it builds the control-plane image from the checkout, names it innerwall:dev, and runs it, whatever .env names. A plain docker compose up -d never builds; it runs the image .env names, as pulled.

Version strings

Both binaries report one version string, semantic-version shaped, with the commit as build metadata:

The commit is the one the Go toolchain embeds in every build made in a git checkout, so a plain make build needs no flags. The Docker image builds with git present for the same reason. A release sets both parts at link time, to the same string a source build of its tag reports.

Untracked files count as uncommitted changes. A checkout holding a file git does not track, such as the docker-compose.override.yml the multi-host guide adds, reports .dirty on every build made from it, make dev included. That is expected, and says nothing about the source. The released image and binaries are not built from your checkout, so they never carry it.

Where each version shows

Upgrading

Upgrade the control plane first, then the agents; each release's notes in CHANGELOG.md say what an older agent keeps doing against a newer control plane. What survives an in-place upgrade, and the steps, are in upgrading in place. A new release is installed as above: download, verify, install. There is no agent self-update, by design (ADR-0011): an agent is upgraded by replacing its binary and restarting the daemon, which re-applies its persisted policy before it dials.