--- title: "Install Viper" description: "Download Viper, point it at your gateway, and create the signing key your agent will use." source: "Guardian Platform" --- 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](./register-agents.mdx). ## 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](./agent-onboarding.mdx#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](./agent-onboarding.mdx#choose-an-environment). ## Get the release With your entitlement token, run the install script: ```bash export VIPER_CLOUDSMITH_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 /.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= 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 `` with `x86_64-linux` or `aarch64-linux` (file `viper-.AppImage`), or `x86_64-darwin` or `aarch64-darwin` (file `viper-.tar.gz`): ```text https://dl.cloudsmith.io//eqtylab/prod/raw/names/viper-/versions/latest/ https://dl.cloudsmith.io//eqtylab/prod/raw/names/viper-checksums/versions/latest/SHA256SUMS ``` 1. 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. 2. On macOS, extract the archive. On Linux, make the AppImage executable with `chmod +x` and rename it `viper`. 3. 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 --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 /.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](./viper-configuration.mdx)). 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](./viper-configuration.mdx#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](./register-agents.mdx), then [run your agent through the gateway](./run-agents.mdx). ## 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 `. | | `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. | ## Related - [Register Agents](./register-agents.mdx) — enroll the new key with Guardian, the next step - [Run Agents](./run-agents.mdx) — start your agent through Viper once it is registered - [Viper Configuration](./viper-configuration.mdx) — the settings file, environment overrides, and hardware signers - [Agent Onboarding](./agent-onboarding.mdx) — supported versions, choosing an environment, and `viper doctor` - [API Keys](./api-keys.mdx) — create the key that enrolls an agent on a headless machine