Install the Gateway

The verdictan command is the CLI and the gateway in one binary. Install it on the computer or server that runs your gateway. Then use the quickstart to connect it to your organization.

If you run the gateway only in Docker, you do not have to install the binary on the host. Use the quickstart in Docker.

Before you start

• macOS on Apple silicon or Intel, Linux on x86_64 or aarch64, or Windows on x86_64.
• Outbound HTTPS access to github.com and verdictan.github.io.
• Administrator rights for APT, DNF, or a system-scope gateway service.

Select your installation

Each channel installs the same verdictan binary. The channel that installs the binary also owns its upgrades.

Channel	Use it when	Upgrade with
Homebrew	You use macOS or Linux with Homebrew.	brew upgrade verdictan
Scoop	You use Windows with Scoop.	scoop update verdictan
APT	You run an amd64 Debian or Ubuntu server.	sudo apt upgrade verdictan
DNF	You run an x86_64 RHEL, CentOS, Fedora, or Amazon Linux 2023 server.	sudo dnf upgrade verdictan-gateway
Official installer	You do not use a package manager.	verdictan-update
Release archive	You must have one exact version or a copy for an air-gapped host.	Download the new archive.
Container image	You run the gateway in Docker or Kubernetes.	Pull the new image tag.

The APT and RPM repositories publish x86_64 packages only. On aarch64 Linux, use Homebrew, the official installer, or a release archive.

Install with a package manager

Homebrew

brew install verdictan/tap/verdictan

Scoop

scoop bucket add verdictan https://github.com/verdictan/packages
scoop install verdictan

APT

1. Download the repository key:

   sudo apt update
   sudo apt install curl gnupg
   curl -fsSL https://verdictan.github.io/packages/keys/verdictan-packages.asc \
     -o /tmp/verdictan-packages.asc
   gpg --show-keys --fingerprint /tmp/verdictan-packages.asc

2. Compare the fingerprint with this value. If the values are different, stop. Do not install the package.

   FBA0 5B9F 2E1E B214 BFC5 2BA2 FDED 465F 123C F517

3. Add the key and the repository. Then install the package:

   sudo gpg --dearmor --yes \
     -o /usr/share/keyrings/verdictan-packages.gpg \
     /tmp/verdictan-packages.asc
   sudo curl -fsSL https://verdictan.github.io/packages/apt/verdictan.list \
     -o /etc/apt/sources.list.d/verdictan.list
   sudo apt update
   sudo apt install verdictan

DNF

1. Add the RPM repository:

   sudo curl -fsSL https://verdictan.github.io/packages/rpm/verdictan.repo \
     -o /etc/yum.repos.d/verdictan.repo

2. Install the package. At the key prompt, compare the fingerprint with FBA0 5B9F 2E1E B214 BFC5 2BA2 FDED 465F 123C F517. If the values are different, answer no.

   sudo dnf install verdictan-gateway

DNF verifies the package signature and the repository metadata signature.

Install with the official installer

The installer downloads the release for your platform and verifies its SHA-256 digest against the signed sha256.sum file. Then it installs verdictan and verdictan-update. It does not register a background service.

Download the installer, read it, and then run your local copy:

macOS or Linux

INSTALLER="$(mktemp)"
curl -fsSL https://verdictan.com/install -o "$INSTALLER"
less "$INSTALLER"
sh "$INSTALLER"
rm "$INSTALLER"

The binaries go in $CARGO_HOME/bin, which is ~/.cargo/bin by default. The installer adds that directory to PATH in your shell profile. To keep your profile unchanged, set VERDICTAN_NO_MODIFY_PATH=1 before you run the installer, and add the directory to PATH yourself.

Windows

$installer = Join-Path $env:TEMP "verdictan-installer.ps1"
Invoke-WebRequest -Uri "https://github.com/verdictan/packages/releases/latest/download/verdictan-installer.ps1" -OutFile $installer
Get-Content $installer
powershell.exe -ExecutionPolicy Bypass -File $installer
Remove-Item $installer

Open a new PowerShell window after the installer completes. The new window has the install directory in PATH.

Install from a release archive

1. Open the latest release.
2. Download the archive for your platform, for example verdictan-aarch64-apple-darwin.tar.gz or verdictan-x86_64-pc-windows-msvc.zip.
3. Download sha256.sum from the same release. Compare the digest of the archive with the listed value.
4. Extract the archive. Move verdictan to a directory on your PATH.

Each release asset also has a .sigstore.json bundle. Use it if your change process requires signature verification.

Run the container image

docker pull verdictan/verdictan:latest
docker run --rm verdictan/verdictan:latest --version

The image contains the same verdictan command. A container without a policy config and a gateway registration does not govern requests. The quickstart in Docker starts a container with both.

Verify the installation

Open a new terminal and run:

verdictan --version
verdictan doctor

verdictan --version prints the installed version. This confirms the installation.

On a new installation, verdictan doctor can report missing authentication or a missing config file. This is expected before setup. The quickstart signs you in and starts a connected gateway.

Run the gateway as a service

A service starts the gateway again after a restart of the host. First, run the gateway in the foreground. Send a request that succeeds. Then install a service with the same agent:

verdictan gateway install \
  --name verdictan-proxy \
  --agent-id <existing-agent-id>

Like the foreground gateway, the service gets its configuration from the control plane. Do not add --policy-config: the service then runs verdictan gateway run --policy-config without --agent, and the gateway does not start. To change the configuration, deploy a version to the agent in Configurations.

The service must have the same provider credentials and gateway runtime token as the foreground gateway. See verdictan gateway for status, logs, and removal.

With CLI 0.1.14 or later, you can deploy a local file through the agent. After deployment, check In sync in Gateways. Then send a test request. The gateway service must also run version 0.1.14 or later to report configuration changes correctly.

Upgrade

Use the upgrade command for the channel that installed the binary. The table in Select your installation lists each command.

verdictan-update replaces the binary at its current path with the latest release. Use it only when no package manager owns the binary. It does not replace a binary while the supervisor manages a gateway service.

For a gateway service, use the supervised upgrade. It records a rollback binary before it changes the service:

verdictan gateway upgrade plan \
  --name verdictan-proxy \
  --target-version <new-version> \
  --binary-path /absolute/path/to/new/verdictan
verdictan gateway upgrade apply --name verdictan-proxy

See verdictan gateway upgrade for status and rollback. For a container, pull the new image tag and create the container again with the same configuration.

Troubleshooting

Problem	Cause	Action
verdictan: command not found after the official installer	The open shell does not have the install directory on PATH.	Open a new terminal, or run export PATH="$HOME/.cargo/bin:$PATH".
The installer reports unsupported platform	Your platform is not in the supported list.	Use the container image.
The installer reports checksum mismatch	The download is incomplete or changed in transit.	Run the installer again. If the error occurs again, stop and report it.
APT or DNF reports a signature error	The key file or the repository file is incomplete.	Do the key and repository steps again and compare the fingerprint.
verdictan-update refuses to run	A supervised gateway service uses the binary.	Use verdictan gateway upgrade plan and apply.

Next steps

• Quickstart: connect this installation and send your first request.
• Manage configuration in a file: write, lint, and test policy-config.yaml.
• verdictan gateway: run and manage the gateway as a service.