Agents ⏱ Reference

CLI Reference

The verifiedproxy npm package provides two commands: install for agent registration and proxy for running the local identity proxy.

On this page
Installation verifiedproxy install verifiedproxy proxy Configuration File Environment Variables

Installation

No global install needed. Run commands directly with npx:

terminal 
npx verifiedproxy <command>

Or install globally:

terminal 
npm install -g verifiedproxy
ℹ️
Requires Node.js 18+. The CLI uses ES modules (.mjs) and modern fetch APIs.

verifiedproxy install

Interactive agent registration wizard. Creates a new agent under your organization and configures the local project.

terminal 
npx verifiedproxy install

Aliases: npx verifiedproxy init

Interactive Prompts

Prompt Default Description
VerifiedProxy API URL https://app.verifiedproxy.com Base URL of the VerifiedProxy API
Organization API Key — Your vp_sk_live_... key from the dashboard
Agent Name — Human-readable name for this agent
Scopes browse Comma-separated list (e.g., browse,data-collect)
Local Proxy Port 8099 Port for the local proxy to listen on

What It Creates

File Purpose
.verifiedproxy.json Agent configuration (API URL, agent ID, name, scopes, proxy port). Add to .gitignore.
AGENT.md Instructions file for the AI agent with identity, scopes, rules, and manual API examples.
.claude/settings.json Claude Code proxy configuration (auto-updated if it exists).
.gitignore Updated to exclude .verifiedproxy.json (auto-updated if it exists).

Example Session

terminal 
$ npx verifiedproxy install

  VerifiedProxy Agent Installer

? VerifiedProxy API URL: https://app.verifiedproxy.com
? Organization API Key: vp_sk_live_a1b2c3d4...
? Agent Name: Acme Research Bot
? Scopes (comma-separated): browse,data-collect
? Local proxy port: 8099

Registering agent...

  Agent registered successfully!

  Agent ID:     ag_a1b2c3d4
  Agent Secret: vp_ag_e5f6a7b8c9d0...

  SAVE YOUR AGENT SECRET NOW — it will not be shown again.

  Config written to .verifiedproxy.json
  Agent instructions written to AGENT.md
  Claude settings updated

  Next steps:
    export VP_AGENT_SECRET=vp_ag_e5f6a7b8c9d0...
    npx verifiedproxy proxy

verifiedproxy proxy

Starts the local HTTP proxy server that intercepts your agent's traffic and attaches verified identity headers.

terminal 
npx verifiedproxy proxy

Prerequisites

  • A .verifiedproxy.json config file (created by install)
  • The VP_AGENT_SECRET environment variable set
terminal 
# Set your agent secret first
export VP_AGENT_SECRET=vp_ag_your_secret_here

# Start the proxy
npx verifiedproxy proxy

How It Works

For HTTP requests:

  • Intercepts the request before it reaches the target
  • Creates a session with the VerifiedProxy API for the target domain
  • Adds X-VP-Agent-Id and X-VP-Session headers to the request
  • Forwards the request to the target

For HTTPS requests (CONNECT tunneling):

  • Intercepts the CONNECT request
  • Creates a session server-side (the proxy can't modify encrypted traffic)
  • Establishes the tunnel to the target
  • Websites verify the agent by calling the VerifiedProxy API with the agent ID and domain

Session Caching

The proxy caches sessions per domain for 8 minutes (sessions expire server-side at 10 minutes). A new session is automatically created when the cache expires.

Graceful Degradation

If session creation fails (network error, API down), the proxy forwards the request anyway without identity headers. Your agent's traffic is never blocked by VerifiedProxy failures.

Output

output 
[VP] VerifiedProxy local proxy running
[VP] Agent: ag_a1b2c3d4 (Acme Research Bot)
[VP] Proxy: http://127.0.0.1:8099
[VP] Waiting for requests...

[VP] 12:00:01 HTTP  example.com         ses_e5f6a7b8
[VP] 12:00:02 HTTPS api.stripe.com      ses_f7a8b9c0
[VP] 12:00:05 HTTPS github.com          ses_a1b2c3d4
[VP] 12:08:01 HTTP  example.com         ses_d5e6f7a8  (new session)

Network Binding

The proxy binds to 127.0.0.1 only (localhost). It is not accessible from other machines on your network.

Configuration File

The .verifiedproxy.json file stores your agent's local configuration:

json 
{
  "apiUrl": "https://app.verifiedproxy.com",
  "agentId": "ag_a1b2c3d4",
  "agentName": "Acme Research Bot",
  "scopes": ["browse", "data-collect"],
  "proxyPort": 8099
}
⚠️
Add .verifiedproxy.json to your .gitignore. It contains your agent ID which, while public, should be kept out of source control as a best practice.

Environment Variables

Variable Required Description
VP_AGENT_SECRET Yes (for proxy) Agent secret from registration. Used to authenticate with the API when creating sessions.
HTTP_PROXY No Set to http://127.0.0.1:8099 to route non-Claude tools through the proxy.
HTTPS_PROXY No Set to http://127.0.0.1:8099 to route HTTPS traffic through the proxy.
Previous ← Register & Manage