Install Viper

Download Viper, point it at your gateway, and create the signing key your agent will use.

Viper is the command-line tool that sits between your agent and the Agent Gateway. It runs a small signing proxy on your machine, so every model request your agent makes reaches the gateway signed with the agent’s own key and carrying a record of the agent’s configuration.

This page gets Viper installed and gives it a key. Registering the agent with Guardian is covered in Register Agents.

Supported platforms

Platform	Architectures	Package
Linux	x86_64, aarch64	AppImage
macOS	x86_64 (Intel), aarch64 (Apple silicon)	`.tar.gz` binary
Containers	linux/amd64, linux/arm64	`docker.cloudsmith.io/eqtylab/prod/viper:latest`

No Windows build is published. For the framework and sandbox versions the integrations support, see Supported versions.

Before you start

A Cloudsmith entitlement token. Viper is published to EQTY Lab’s private Cloudsmith repository; ask your EQTY Lab contact for a token.
curl, and sha256sum or shasum, which the install script uses to download and check the release. macOS and most Linux distributions include them.
Your gateway address, from your administrator. Guardian’s Register Agent dialog also shows it in the commands it gives you, when your deployment is configured to. If you use more than one Guardian Platform deployment, see Choose an environment.

Get the release

With your entitlement token, run the install script:

bash

export VIPER_CLOUDSMITH_TOKEN=<your entitlement token>
curl -fsSL "https://dl.cloudsmith.io/$VIPER_CLOUDSMITH_TOKEN/eqtylab/prod/raw/names/viper-install/versions/latest/install.sh" | sh

It ends by naming the version it installed:

console

Installed viper 0.3.0 to <home>/.local/bin/viper

The script downloads the latest release for your platform, checks it against the release’s SHA256SUMS, and installs viper to ~/.local/bin. Set VIPER_VERSION to install a specific version released after 0.2.1, or VIPER_INSTALL_DIR to install somewhere else. Set them on sh, not curl, so the script sees them:

bash

curl -fsSL "https://dl.cloudsmith.io/$VIPER_CLOUDSMITH_TOKEN/eqtylab/prod/raw/names/viper-install/versions/latest/install.sh" | VIPER_VERSION=<version> sh

If ~/.local/bin is not on your PATH, the script says so. To upgrade, run the same command again.

Download by hand

Each platform’s file has a fixed URL. Replace <system> with x86_64-linux or aarch64-linux (file viper-<system>.AppImage), or x86_64-darwin or aarch64-darwin (file viper-<system>.tar.gz):

text

https://dl.cloudsmith.io/<token>/eqtylab/prod/raw/names/viper-<system>/versions/latest/<file>
https://dl.cloudsmith.io/<token>/eqtylab/prod/raw/names/viper-checksums/versions/latest/SHA256SUMS

Check the download with sha256sum --check --ignore-missing SHA256SUMS (on macOS, shasum -a 256 --check --ignore-missing SHA256SUMS). A release’s files are uploaded one at a time, so if the check fails within a few minutes of a release, download both files again.
On macOS, extract the archive. On Linux, make the AppImage executable with chmod +x and rename it viper.
Move the viper binary somewhere on your PATH, such as /usr/local/bin.

Verify the install

bash

viper --version

console

viper 0.3.0

Viper prints its version. viper --help lists every command, and viper <command> --help describes one.

Point Viper at your gateway

The first time you run a Viper command other than --version, --help, viper doctor, or viper ca, Viper notices it has no configuration and asks for your gateway URL:

console

No Viper config file found at <home>/.config/viper/config.toml.
Let's set one up.
Enter your gateway URL (example: https://gateway.example.com).
Gateway URL:

Enter the gateway’s origin only, such as https://gateway.example.com, without /v1: Viper adds /v1 itself. If you leave off https://, Viper adds that too. Viper writes the answer to ~/.config/viper/config.toml (see Viper Configuration).

On a machine with no interactive terminal, such as CI or a container, set VIPER_GATEWAY_URL before the first run and Viper creates the file without prompting.

Create a key

Each agent signs its requests with a key that Viper holds. Create one and assign it to the agent you plan to run in one step:

bash

viper did add --assign claude

console

assigned `did:key:z6Mk…` to `claude`
did:key:z6Mk…

The last line is always the bare key identifier. The --assign value names the app the key belongs to: claude, codex, opencode, openclaw, or proxy (for any other agent).

By default the key is a software key stored in ~/.config/viper/keys/, readable only by your user account. Viper also supports hardware-backed signers: a YubiKey (--signer-type yubikey) and a vComp Notary (--signer-type vcomp-notary), which signs on Viper’s behalf so no private key is kept locally. A YubiKey must already have a key provisioned in its signing slot before Viper can use it. See Key storage and signers.

Assign a key to an app

If you created a key without --assign, or you want to switch keys, assign it afterward:

bash

viper did assign                                        # choose interactively
viper did assign --app codex --did did:key:z6Mk...      # non-interactive
viper did list                                          # show keys and their apps

Each app uses its own key. Assigning a key that another app holds moves it to the new app, and assigning one to an app that already has a key replaces that key. Viper asks before either; add --force to skip the question, which a shell with no terminal requires.

Register the agent

A key on its own does not let traffic through the gateway. Register it with Guardian next, using an API key for headless machines or a registration token from the Agent Catalog. Follow Register Agents, then run your agent through the gateway.

Viper in containers

The Viper container image carries Viper and the libraries it needs. Copy both into your own image:

dockerfile

FROM docker.cloudsmith.io/eqtylab/prod/viper:latest AS viper

FROM python:3.13-slim
COPY --from=viper /nix/store/ /nix/store/
COPY --from=viper /usr/local/bin/ /usr/local/bin/
RUN viper --version

# Continue with your application's setup, USER, and CMD.

Keep both COPY lines; Viper needs its bundled libraries at their original paths. Viper needs no extra container privileges. Your image must provide CA certificates for HTTPS, a writable home directory for the user that runs Viper, and the agent CLI itself (for example Claude Code) if you plan to use a wrapper command.

Before you build, log in to the registry with the same entitlement token, entering it as the password:

bash

docker login docker.cloudsmith.io --username eqtylab/prod

Troubleshooting

Symptom	What to do
The install script `could not download` a file	Check that `VIPER_CLOUDSMITH_TOKEN` holds a current token, and that `VIPER_VERSION`, if set, is a released version.
The install script says `set VIPER_CLOUDSMITH_TOKEN`	Export the entitlement token your EQTY Lab contact gave you, then run the command again.
The install script says `no Viper build for` your system	Viper is built for Linux and macOS on x86_64 and aarch64 only. On Windows, the Linux build may run under WSL2, but it is not tested there.
The install script says `curl is needed` or `sha256sum or shasum is needed`	Install the tool it names with your package manager, then run the command again.
The install script says `SHA256SUMS has no entry` for a file	The release’s checksum list has no entry for your platform’s file. Tell your EQTY Lab contact, or set `VIPER_VERSION` to an earlier release.
The install script says a file `does not match SHA256SUMS`	Nothing was installed. Retry, and tell your EQTY Lab contact if it keeps happening.
`config file not found ... and no interactive terminal is available for setup`	Set `VIPER_GATEWAY_URL` before running Viper.
The install script says `AppArmor blocks the user namespace` Viper needs	Ubuntu 23.10 and later stop unprivileged programs from creating user namespaces, which the Linux AppImage needs to start, and extracting the AppImage does not avoid this. Allow them with `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, which lasts until reboot; to keep it, add `kernel.apparmor_restrict_unprivileged_userns=0` to a file in `/etc/sysctl.d/`. This loosens the restriction for every program on the machine, so check with whoever manages it first.
The Linux AppImage fails to start because FUSE is unavailable	Run `./viper --appimage-extract`, then use `squashfs-root/AppRun` in place of the AppImage.
macOS blocks the binary because it cannot verify the developer	The macOS build is not notarized. Remove the download quarantine with `xattr -d com.apple.quarantine ./viper`.
`DID ... is assigned to multiple apps`	Each app needs its own key, and every Viper command stops until the file is fixed. In `config.toml`, delete one of the two apps’ lines under `[default_dids]`, then create a key for that app with `viper did add --assign <app>`.
`viper: command not found`	The binary is not on your `PATH`. Move it to a directory on `PATH` or call it by its full path.

Register Agents — enroll the new key with Guardian, the next step
Run Agents — start your agent through Viper once it is registered
Viper Configuration — the settings file, environment overrides, and hardware signers
Agent Onboarding — supported versions, choosing an environment, and viper doctor
API Keys — create the key that enrolls an agent on a headless machine

Supported platforms

Before you start

Get the release

Download by hand

Verify the install

Point Viper at your gateway

Create a key

Assign a key to an app

Register the agent

Viper in containers

Troubleshooting

Related