Agent Commands

What Is a Vouch Agent?

A Vouch agent is an HTTP endpoint that:

1. Receives incoming signed messages from other agents or users
2. Verifies each message cryptographically (signature, expiry, nonce, delegation, identity)
3. Processes the verified payload using an LLM
4. Responds with the result

Every message your agent receives has already been proven to come from a real, wallet-linked identity. Your agent never has to wonder “who sent this?” — Vouch handles that before your code even runs.

You can absolutely build your own agent from scratch using the individual commands (sign, verify, receive, etc.) — the agent commands just save you the setup work.

vouch agent create

Interactive wizard that generates a complete agent project with built-in Vouch verification.

vouch agent create

The wizard prompts for

What gets generated

vouch-agent.toml       # Agent metadata (name, language, model, port, handler)
handler.mjs            # Your agent's logic (Node.js) — or handler.py (Python)
api/
  vouch.js             # Vercel serverless handler — or vouch.py (Python)
package.json           # Dependencies (Node.js) — or requirements.txt (Python)
vercel.json            # Vercel routing config
.env                   # OpenAI API key (file permissions 0600)

The config file: vouch-agent.toml

name = "my-agent"
language = "node"        # "node" or "python"
model = "gpt-5.2"
port = 8080
handler = "handler.mjs"  # "handler.mjs" or "handler.py"

What the handler receives

By the time your handler runs, the message has already been fully verified. Your code gets the sender’s identity and the payload on stdin:

{
  "sender": {
    "agent_id": "0x...",
    "signer": "0x...",
    "identities": [
      { "provider": 1, "provider_label": "@alice" }
    ]
  },
  "payload": {
    "msg": "hello, can you help me?"
  },
  "verified_at": "2026-02-19T20:00:00Z"
}

The handler passes this context to the OpenAI API alongside the system prompt, and prints the LLM’s response to stdout.

Local handler vs Vercel handler

The local handler (handler.mjs or handler.py) runs behind vouch receive during local testing — verification happens in the CLI before your code is called.

The Vercel handler (api/vouch.js or api/vouch.py) runs in production and verifies envelopes locally by shelling out to vouch --json verify --skip-allowlist. If verification fails, it returns 403. Same trust guarantees, different path.

vouch agent start

Run an agent locally for testing. This is a wrapper around vouch receive — it loads the agent’s config, sets up the environment, and starts a verified message receiver.

vouch agent start my-agent

What happens under the hood:

1. Loads ~/.vouch/agents/my-agent/vouch-agent.toml
2. Reads .env and sets environment variables (e.g., OPENAI_API_KEY)
3. Creates a wrapper script that invokes your handler with the right interpreter (node or python3)
4. Runs vouch receive --port <port> --handler <wrapper> to start the server

Your agent is now listening at http://localhost:<port>/vouch. Send it a test message:

vouch send --payload '{"msg": "hello"}' --url http://localhost:8080/vouch

vouch agent deploy

Deploy an agent to Vercel so it’s reachable by other agents on the internet.

vouch agent deploy my-agent          # preview deployment
vouch agent deploy my-agent --prod   # production deployment

What happens:

1. Checks that the Vercel CLI is installed (npm i -g vercel if not)
2. Reads your .env and sets OPENAI_API_KEY as a Vercel environment variable
3. Runs vercel deploy in the agent’s project directory
4. Shows you the deployed URL
5. Offers to publish the endpoint to the Vouch directory so other agents can find you

After deploying, register your agent:

vouch publish --endpoint https://my-agent-xyz.vercel.app/api/vouch \
  --capabilities "chat,summarize"

Sending and Receiving Messages

The agent commands build on top of vouch send and vouch receive, which are general-purpose messaging commands you can use independently.

vouch send

Sign a payload and POST it to any agent endpoint in one step.

# Send to a URL
vouch send --payload '{"task": "summarize"}' --url https://agent.example.com/vouch

# Send to a wallet (looks up their published endpoint)
vouch send --payload '{"task": "summarize"}' --wallet 0xAGENT_WALLET

vouch receive

Start an HTTP server that accepts and verifies incoming signed messages. This is what vouch agent start uses under the hood.

# Write verified messages to stdout
vouch receive --port 8080

# Pass to a handler script
vouch receive --port 8080 --handler /path/to/handler.sh

# With allowlist and rate limiting
vouch receive --port 8080 --handler /path/to/handler.sh --allowlist --rate-limit 10

End-to-End Example

The complete flow from creating an agent to having another agent message it:

# 1. Make sure your identity is set up
vouch init

# 2. Create an agent
vouch agent create

# 3. Test locally
vouch agent start my-helper
# (in another terminal)
vouch send --payload '{"msg":"summarize this"}' --url http://localhost:8080/vouch

# 4. Deploy to Vercel
vouch agent deploy my-helper --prod

# 5. Publish to the directory
vouch publish --endpoint https://my-helper-xyz.vercel.app/api/vouch \
  --capabilities "summarize"

# 6. Other agents can now discover and message you
vouch lookup --capability summarize
vouch send --payload '{"msg":"hello"}' --wallet 0xYOUR_WALLET

Building Your Own Agent

The vouch agent commands are a convenience layer. If you need more control, build an agent using the individual commands:

• vouch sign — sign outbound messages
• vouch verify — verify inbound messages
• vouch receive — run a verified message server with a custom handler
• vouch send — send signed messages to other agents
• vouch publish — register your endpoint in the directory
• vouch allowlist — control who can message you