Agent Onboarding

Onboarding an agent takes four steps: install Viper, enroll the agent, run it through Viper, and confirm its requests in Guardian. This page lays out the path, what it supports, and where to look when a step fails.

The path

1. Install Viper on the machine where the agent runs, and point it at your gateway. See Install Viper.
2. Enroll the agent. Give it a key and register the key with Guardian. See Register Agents, or the enrollment step of the quickstart you follow. The Register Agent dialog in Guardian shows the install, enroll, check and run commands for the agent type you choose.
3. Run the agent through Viper. How depends on the agent; see Choose your integration.
4. Check the setup with viper doctor, then find the agent in the Agent Catalog and associate it with a project so project policy applies to it.

The whole path at once

For Claude Code, with an API key that has the Register Agents scope, the path is:

# 1. Install Viper with your Cloudsmith entitlement token
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

# 2. Create a key for Claude Code and register it; the first run asks for your gateway URL
viper did add --assign claude
GUARDIAN_API_KEY=ak_… viper did register --app claude --agent-name "my-laptop"

# 3. Check the setup, then run Claude Code through the gateway
viper doctor
viper claude

Other agents follow the same shape; the page in Choose your integration gives the commands for each.

Choose your integration

What the Guardian Platform records for each, and what it does not, is on Agent Coverage.

Supported versions

On Windows, the Linux build may run under WSL2, but it is not tested there. Deep Agents changes quickly before its 1.0 release, so only 0.7.x is supported. OpenShell does not run on Intel Macs, and its other drivers (Podman, Kubernetes, MicroVM) are not tested.

Choose an environment

Each Guardian Platform deployment has its own gateway. Viper registers keys with, and signs for, the gateway in llm_gateway_api_url, or in VIPER_GATEWAY_URL when that is set, which overrides the file every time Viper starts. Use the gateway address your administrator gives you for the deployment you mean to use; Viper has no built-in list of environments to pick from. A viper proxy sends model traffic to --gateway-endpoint but still uses the configured gateway for everything else, so give both the same deployment’s address.

A key registered with one deployment is unknown to every other. Changing only the gateway address leaves Viper signing with keys the new gateway refuses, as signing key is not registered. Registering with an API key or token that another deployment issued fails with registration_invalid_token.

To use more than one deployment from the same machine, keep a configuration directory for each and choose it with VIPER_CONFIG. Viper keeps the keys, credentials and logs beside the configuration file, so each directory has its own. Give the gateway address once, when the directory is created:

export VIPER_CONFIG=~/.config/viper-staging/config.toml
VIPER_GATEWAY_URL=https://gateway.staging.example.com viper did add --assign proxy
GUARDIAN_API_KEY=ak_… viper did register --app proxy --agent-name "checkout-bot"

viper did add creates the configuration with that gateway, and later commands read it from the file. Keep VIPER_GATEWAY_URL out of your shell profile when you switch deployments this way, because it would override every directory’s address. Enroll each agent again in each deployment, with an API key or token that deployment issued. See Viper Configuration.

Check your setup with viper doctor

viper doctor checks that Viper is ready to sign for each key on this machine, and prints a fix for each problem it finds:

$ viper doctor
pass  config             <home>/.config/viper/config.toml
pass  gateway            https://gateway.example.com (llm-gateway 1.2.1)
pass  agent support-bot  did:key:z6Mk… is registered, and the gateway accepts its signature
pass  app proxy          did:key:z6Mk… is registered, and the gateway accepts its signature
skip  local CA           none yet; only `--egress-capture` uses one, and creates it

It checks the configuration file, that the gateway answers, that each agent and app key is registered and accepted, and the local certificate --egress-capture uses. To check a key, it signs a request that renews the key’s credential and discards the result. It changes no configuration, keys or credentials; like every Viper command, it writes a session log.

Because the exit status reflects failures only, viper doctor can gate a script, a container start, or a CI job. Use VIPER_CONFIG to check a configuration other than the default.

What doctor reports

Troubleshooting

Each step has its own troubleshooting table, keyed by the message Viper prints:

Viper writes a log file for each session in logs/ beside the configuration file, ~/.config/viper/logs/ by default. When a request fails, the newest log says why.

Related

• Install Viper — download Viper, point it at your gateway, and create a key
• Register Agents — enroll the agent with an API key or a registration token
• Run Agents — wrapper and sidecar commands for each supported agent
• Audit Trail — confirm the agent’s requests were recorded
• Agent Configuration — what Viper captures about the agent at the start of each session
• Roles and Permissions — the Agent Operator role and the Register Agents permission