Running the Proxy

The local proxy is the core of VerifiedProxy. It sits between your AI agent and the internet, automatically attaching identity to every request.

Starting the Proxy

terminal

# 1. Set your agent secret
export VP_AGENT_SECRET=vp_ag_your_secret_here

# 2. Start the proxy
npx verifiedproxy proxy

The proxy reads your .verifiedproxy.json for configuration and starts listening on the configured port.

Request Flow

HTTP Requests

For plain HTTP traffic, the proxy can directly modify requests:

flow

1. Agent sends HTTP request to proxy (port 8099)
2. Proxy checks session cache for the target domain
3. If no cached session, creates one via VerifiedProxy API
4. Proxy adds headers to the request:
     X-VP-Agent-Id: ag_a1b2c3d4
     X-VP-Session: ses_e5f6a7b8
5. Proxy forwards the modified request to the target
6. Target website receives the request with identity headers

HTTPS Requests (CONNECT Tunnel)

For HTTPS traffic, the proxy cannot modify encrypted requests. Instead, it creates a session server-side:

flow

1. Agent sends CONNECT request to proxy
2. Proxy creates session via VerifiedProxy API for the target domain
3. Proxy establishes TCP tunnel to the target
4. Agent communicates directly with target through encrypted tunnel
5. Target verifies agent by calling:
     GET /api/agents/verify?agent_id=ag_...&url=https://target.com

ℹ️

For HTTPS, the website verifies the agent using the public API with the agent ID and its own domain. The VerifiedProxy API returns the matching session if one was recently created for that domain.

Session Lifecycle

Event	Timing	Action
First request to domain	Immediate	New session created, cached locally
Subsequent requests	Within 8 min	Cached session reused (no API call)
Cache expires	After 8 min	New session created automatically
Server expiry	After 10 min	Session invalid for verification

The 2-minute buffer between client cache (8 min) and server expiry (10 min) ensures sessions are always valid when used.

Headers Added

Header	Value	Description
`X-VP-Agent-Id`	`ag_a1b2c3d4`	Your agent's unique identifier
`X-VP-Session`	`ses_e5f6a7b8`	Current session for this domain

Error Handling

The proxy is designed to never block your agent's traffic:

Scenario	Behavior
API unreachable	Request forwarded without identity headers
Session creation fails	Request forwarded without identity headers
Invalid agent secret	Session creation returns 401; request forwarded without headers
Agent revoked	Session creation returns 403; request forwarded without headers

✅

The proxy follows a fail-open design. If anything goes wrong with VerifiedProxy, your agent continues working normally — just without verified identity headers.

Manual Session Creation

You can create sessions directly without the proxy, useful for testing or custom integrations:

curl

# Create a session for a target domain
curl -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": "browse",
    "metadata": {"purpose": "research"}
  }'

200 OK

json

{
  "session_id": "ses_e5f6a7b8",
  "agent_id": "ag_a1b2c3d4",
  "target_url": "https://example.com",
  "expires_at": "2026-03-06T12:10:00Z",
  "visit_url": "https://example.com?vp_agent=ag_a1b2c3d4&vp_session=ses_e5f6a7b8"
}