Installation

Installation

Prerequisites

Keyseal has two different installation profiles. Do not install extra tools on production servers unless that machine actually mutates encrypted files.

Keyseal uses the official SOPS Go decrypt library for read-only decryption in render, exec, and validation paths. The external SOPS binary is still required for commands that create, edit, or rotate encrypted files.

Developer/admin machine

Required:

• keyseal
• external sops binary on PATH or configured with sops.binary
• age key material for files you need to decrypt/edit

Used for:

• keyseal add
• keyseal edit
• keyseal updatekeys
• encrypting, editing, or rotating encrypted files

The age CLI is useful here for key generation and inspection:

sops --version
age --version
age-keygen -o ~/.config/sops/age/keys.txt

Production/server/CI/deploy machine

Required:

• keyseal
• encrypted secrets files/repo
• age private key material, usually via SOPS_AGE_KEY_FILE or sops.age_key_file

Not required for read-only operations:

• external sops binary
• external age binary

Used for:

• keyseal render
• keyseal exec
• keyseal doctor decrypt validation
• keyseal verify

Servers need the age key, not the age CLI.

Go 1.25 or later is required to build from source.

---

Release binaries

Pre-built archives for the four supported platforms are attached to each tagged GitHub release:

keyseal_<version>_linux_amd64.tar.gz
keyseal_<version>_linux_arm64.tar.gz
keyseal_<version>_darwin_amd64.tar.gz
keyseal_<version>_darwin_arm64.tar.gz
keyseal_<version>_checksums.txt

Each archive contains the keyseal binary, README.md, and LICENSE.

# example: linux amd64
curl -LO https://github.com/Barkway-app/keyseal/releases/download/v1.0.0/keyseal_v1.0.0_linux_amd64.tar.gz
tar xzf keyseal_v1.0.0_linux_amd64.tar.gz
sudo mv keyseal /usr/local/bin/

# verify checksum before moving the binary
sha256sum -c keyseal_v1.0.0_checksums.txt --ignore-missing

---

Build from source

git clone https://github.com/Barkway-app/keyseal
cd keyseal
make build

The binary lands at ./bin/keyseal. The build embeds version metadata from Git tags and the current HEAD commit. A clean tag produces a version string like v1.0.0 (abc1234); a build with no tags produces dev (abc1234).

To install it system-wide:

sudo cp ./bin/keyseal /usr/local/bin/

---

Verification

# check binary is accessible
keyseal --version

# expected output format:
# keyseal v1.0.0 (abc1234)

For a more detailed version output:

keyseal version
# keyseal v1.0.0 (abc1234)
# tag: v1.0.0
# commit: abc1234
# built: 2026-04-19T13:10:00Z

---

SOPS binary path

sops.binary is only used for mutating SOPS CLI operations (add, edit, and updatekeys). Read-only decrypt/render/exec/validation paths do not use this binary.

If SOPS is installed outside PATH on a developer/admin machine, override it in keyseal.yaml:

sops:
  binary: /usr/local/bin/sops

See Configuration Reference for details.

If the age CLI is installed outside PATH on a developer/admin machine, configure it too. This is not required on production servers that only decrypt with existing age key material:

sops:
  age_binary: /usr/local/bin/age

---

The age key file

Set sops.age_key_file in keyseal.yaml to the private key path you want Keyseal to use by default. Keyseal passes that path to the SOPS Go decrypt library for read-only operations and to the SOPS CLI for mutating operations.

If SOPS_AGE_KEY_FILE is already set in the shell, the environment variable wins. That makes it easy to keep a stable local default in config while still overriding it for CI or one-off commands.

---

Production deployment example

A read-only deploy host can intentionally contain only Keyseal, the encrypted repo, and the age private key material:

/usr/local/bin/keyseal
/srv/my-app/secrets/keyseal.yaml
/srv/my-app/secrets/production/platform/app.enc.yaml
/etc/keyseal/age.key

No external sops or age binaries are required for this server-side render:

cd /srv/my-app/secrets
SOPS_AGE_KEY_FILE=/etc/keyseal/age.key \
  /usr/local/bin/keyseal render production/platform/app --out /run/secrets/app.env

The same host can run keyseal exec or keyseal verify with the same age key material. If that host ever needs to run keyseal add, keyseal edit, or keyseal updatekeys, install the external SOPS binary first.