Quick Start

Get a verified AI agent up and running on your Mac in under 5 minutes. This guide covers everything from installing the prerequisites to starting the proxy alongside Claude Code or the Claude Agent SDK.

What You'll Need

• A Mac with macOS Ventura or later
• Terminal (built-in — open it from Applications → Utilities → Terminal, or just press Cmd + Space and type "Terminal")
• Node.js 18+ (we'll install it below if you don't have it)
• An AI agent that makes HTTP requests — like Claude Code or an app built with the Claude Agent SDK

Don't have Node.js yet?

Open Terminal and paste this. It installs Homebrew (Mac's package manager), then Node.js:

# Install Homebrew (skip if you already have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

Verify it worked:

node --version   # should print v18 or higher

Step-by-Step Setup

1. Create a VerifiedProxy account

   Go to app.verifiedproxy.com/signup and create an account with your org name, email, and a password.

   After signing up, you'll land on your dashboard. Your API key is displayed there — it looks like vp_sk_live_a1b2c3d4...

   🔒

   Copy your API key right now. It's only shown once. You'll need it in the next step.

2. Open Terminal and cd into your project

   Navigate to the folder where you'll be running your agent. For example:

   terminal Copy

   cd ~/my-project

3. Run the installer

   This single command registers your agent and configures everything:

   terminal Copy

   npx verifiedproxy install

   It'll ask you a few questions:

   Question	What to enter
   API base URL	Just press Enter (uses the default https://app.verifiedproxy.com)
   Org API key	Paste the vp_sk_live_... key from step 1
   Agent name	A name for this agent, e.g. My Research Bot
   Scopes	What the agent can do. Press Enter for browse, or type browse,data-collect
   Local proxy port	Press Enter for 8099 (the default)

   When it's done, you'll see your Agent ID and Agent Secret:

   output

     Agent registered successfully!
   
     Agent ID:     ag_a1b2c3d4
     Agent Secret: vp_ag_e5f6a7b8c9d0...
   
     SAVE YOUR AGENT SECRET NOW — it will not be shown again.

   🔒

   Copy the Agent Secret immediately. It's shown only once. You can't retrieve it later.

   The installer also creates these files in your project:

   • .verifiedproxy.json — your agent config (auto-added to .gitignore)
   • AGENT.md — instructions that your AI agent can read
   • .claude/settings.json — tells Claude Code to route traffic through the proxy

4. Set your agent secret

   In the same Terminal window, export the secret as an environment variable:

   terminal Copy

   export VP_AGENT_SECRET="vp_ag_your_secret_here"

   ℹ️

   This only lasts for the current Terminal session. To make it permanent, add the export line to your ~/.zshrc file (Mac's default shell config). The installer may have already done this for the CA certificate — you can add the secret on the next line.

5. Start the proxy

   With the secret set, start the local proxy:

   terminal Copy

   npx verifiedproxy proxy

   You should see:

   output

     VerifiedProxy Proxy
     ───────────────────
   
     Agent:    My Research Bot (ag_a1b2c3d4)
     Proxy:    http://127.0.0.1:8099
     API:      https://app.verifiedproxy.com
   
     Listening for requests. Press Ctrl+C to stop.

   Leave this Terminal window open. The proxy needs to keep running while your agent works.

6. Start your agent

   Open a new Terminal tab (Cmd + T) and start your agent from the same project folder. The proxy runs in the background in the other tab.

   Using Claude Code

   Just start Claude Code like you normally would:

   terminal Copy

   cd ~/my-project
   claude

   That's it. The installer already configured .claude/settings.json to route traffic through the proxy. Every HTTP request Claude Code makes will automatically carry your verified identity.

   Using the Claude Agent SDK

   If you're building a custom agent with the Claude Agent SDK, set the proxy environment variables before running your app:

   terminal Copy

   # Point your agent's HTTP traffic through the proxy
   export HTTP_PROXY=http://127.0.0.1:8099
   export HTTPS_PROXY=http://127.0.0.1:8099
   
   # If the installer generated a CA certificate, trust it
   export NODE_EXTRA_CA_CERTS=~/.verifiedproxy/certs/ca.crt
   
   # Run your agent
   node my-agent.js

   Using any other agent or tool

   Any tool that respects the standard HTTP_PROXY / HTTPS_PROXY environment variables will work. Just export them as shown above, then run your tool.

Check that it's working

When your agent makes requests, you'll see activity in the proxy's Terminal tab:

  12:00:01  [CONNECT]  example.com       ses_e5f6a7b8
  12:00:02  [CONNECT]  api.stripe.com    ses_f7a8b9c0
  12:08:01  [CONNECT]  example.com       ses_d5e6f7a8  (new session — old one expired)

Each line means the proxy successfully created a verification session for that domain. Websites can now verify your agent's identity.

Manual test (optional)

You can verify it end-to-end with two curl commands:

# 1. Create a test session
curl -s -X POST https://app.verifiedproxy.com/api/agents/sessions \
  -H "Authorization: Bearer $VP_AGENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com", "action": "test"}'

# Copy the session_id from the response, then:

# 2. Verify it (this is what websites do — no auth needed)
curl -s "https://app.verifiedproxy.com/api/agents/verify?agent_id=ag_YOUR_ID&session=ses_YOUR_SESSION"

If you see "verified": true, everything is working.

Day-to-day workflow

Once set up, your daily routine is just two commands:

# Tab 1: Start the proxy
cd ~/my-project
export VP_AGENT_SECRET="vp_ag_..."
npx verifiedproxy proxy

# Tab 2: Start your agent
cd ~/my-project
claude   # or: node my-agent.js

Troubleshooting

Port already in use

If you see "Error: Port 8099 is already in use", another proxy instance is still running. Find and stop it:

lsof -i :8099   # shows what's using the port
kill <PID>      # stop it

VP_AGENT_SECRET not set

The proxy will tell you if the secret is missing. Make sure you ran the export command in the same Terminal tab where you start the proxy.

.verifiedproxy.json not found

Make sure you cd into the project folder where you ran npx verifiedproxy install before starting the proxy.

What's Next?