Quickstart

Get your first Vestauth agent running in 2 minutes

Installation

Install Vestauth globally via npm:

npm i -g vestauth

For other installation methods, see the Installation guide.

Create Your First Agent

Initialize a new agent in your current directory. This creates a .env file with your agent’s cryptographic identity.

1. Initialize the agent

   Run the init command to generate your agent’s keypair:

   vestauth agent init
   

   You’ll see output like:

   ✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
   ⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]
   

   Your agent’s identity is stored in .env with three values:

   • AGENT_UID - Your agent’s unique identifier
   • AGENT_PUBLIC_JWK - Your public key (safe to share)
   • AGENT_PRIVATE_JWK - Your private key (keep secret!)
2. Verify your agent identity

   Make your first authenticated request to the whoami endpoint:

   vestauth agent curl https://api.vestauth.com/whoami --pp
   

   The --pp flag pretty-prints the JSON response:

   {
     "uid": "agent-4b94ccd425e939fac5016b6b",
     "kid": "B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I",
     "public_jwk": {
       "crv": "Ed25519",
       "x": "py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg",
       "kty": "OKP",
       "kid": "B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"
     },
     "well_known_url": "https://agent-4b94ccd425e939fac5016b6b.api.vestauth.com/.well-known/http-message-signatures-directory"
   }
   

   The response shows your agent’s public identity and the .well-known URL where tools can discover your public key.

3. Call your first tool

   Let’s write a file using the SFS (Simple File System) tool:

   vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"Hello from my agent!"}'
   

   Now list your files:

   vestauth agent curl https://sfs.vestauth.com/list --pp
   

   And read the file back:

   vestauth agent curl https://sfs.vestauth.com/read -d '{"filepath":"/hello.md"}'
   

   Every request is cryptographically signed with your agent’s private key. The tool verifies your identity before executing.

Understanding Agent Identity

Let’s look at what vestauth agent init created in your .env file:

.env

AGENT_UID="agent-4b94ccd425e939fac5016b6b"
AGENT_PUBLIC_JWK='{"crv":"Ed25519","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}'
AGENT_PRIVATE_JWK='{"crv":"Ed25519","d":"Z9vbwN-3eiFMVv_TPWXOxqSMJAT21kZvejWi72yiAaQ","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}'

Never share your AGENT_PRIVATE_JWK! This is your agent’s secret key. Anyone with access to it can impersonate your agent.

How Signing Works

When you run vestauth agent curl, it automatically:

1. Reads your private key from .env
2. Signs the HTTP request with cryptographic headers
3. Sends the signed request to the tool

You can peek at the signed headers:

vestauth agent headers GET https://api.vestauth.com/whoami --pp

{
  "Signature": "sig1=:d4Id5SXhUExsf1XyruD8eBmlDtWzt/vezoCS+SKf0M8CxSkhKBtdHH7KkYyMN6E0hmxmNHsYus11u32nhvpWBQ==:",
  "Signature-Input": "sig1=(\"@authority\");created=1770247189;keyid=\"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I\";alg=\"ed25519\";expires=1770247489;nonce=\"NURxn28X7zyKJ9k5bHxuOyO5qdvF9L5s2qHmhTrGUzbwGSIoUCHmwSlwiiCRgTDGuum83yyWMHJU4jmrVI_XPg\";tag=\"web-bot-auth\"",
  "Signature-Agent": "sig1=agent-4b94ccd425e939fac5016b6b.api.vestauth.com"
}

These headers follow the RFC 9421 specification for HTTP Message Signatures.

Try More Tools

SFS - Simple File System

# Write files
vestauth agent curl https://sfs.vestauth.com/write \
  -d '{"filepath":"/notes.txt", "content":"My notes"}'

# List files
vestauth agent curl https://sfs.vestauth.com/list

# Delete files
vestauth agent curl https://sfs.vestauth.com/delete \
  -d '{"filepath":"/notes.txt"}'

GEO - Location

# Get latitude and longitude
vestauth agent curl https://geo.vestauth.com/geo --pp

AS2 - Secret Storage

# Set a secret
vestauth agent curl https://as2.dotenvx.com/set \
  -d '{"API_KEY":"secret-value"}'

# Get all secrets
vestauth agent curl https://as2.dotenvx.com/get --pp

Docle - Email Verification

# Verify an email address
vestauth agent curl https://docle.co/api/verify \
  -d '{"emails":["[e-mail]"]}' --pp

Key Rotation

Rotate your agent’s keys while keeping the same identity:

vestauth agent rotate

✔ agent keys rotated (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]

This generates new public and private keys but preserves your AGENT_UID.

Using Vestauth in Code

You can use Vestauth programmatically in your JavaScript/TypeScript applications:

Initialize Agent

const vestauth = require('vestauth')

// Initialize a new agent
const result = await vestauth.agent.init()
console.log(result.AGENT_UID)
// agent-4b94ccd425e939fac5016b6b

Next Steps

Explore Tools

Learn about all available first-party and third-party tools

Build Your Own Tool

Create authenticated APIs with vestauth.tool.verify()

Self-Host Vestauth

Run your own Vestauth infrastructure

Advanced CLI Usage

Master the Vestauth CLI commands