vestauth

curl -L -o vestauth.tar.gz "https://github.com/vestauth/vestauth/releases/latest/download/vestauth-$(uname -s)-$(uname -m).tar.gz"
tar -xzf vestauth.tar.gz
./vestauth agent init

Download the windows executable directly from the releases page.

• vestauth-windows-amd64.zip
• vestauth-windows-x86_64.zip

(unzip to extract vestauth.exe)

Identity

Give agents cryptographic identities.

$ mkdir your-agent
$ cd your-agent

$ vestauth agent init
✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)

Your agent's identity lives in a simple .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"}"

💬 Ask ChatGPT: Are HTTP message signatures more secure than API keys?

Tools

Call tools!

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

First Party

SFS is a simple file system for vestauth agents.

sfs.vestauth.com

# write a file
vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'

# delete a file
vestauth agent curl https://sfs.vestauth.com/delete -d '{"filepath":"/hello.md"}'

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

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

SAM is a simple way to send email for vestauth agents.

sam.vestauth.com

# send an email
vestauth agent curl https://sam.vestauth.com/send -d '{"to":"you@email.com", "text":"i am agent"}'

GEO returns the current latitude and longitude of a vestauth agent.

geo.vestauth.com

# return latitude and longitude
vestauth agent curl https://geo.vestauth.com/geo

Third Party

AS2 is a simple, agent-friendly secret storage.

as2.dotenvx.com

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

# get all secrets
vestauth agent curl "https://as2.dotenvx.com/get"

# get single secret
vestauth agent curl "https://as2.dotenvx.com/get?key=KEY"

# get multiple secrets
vestauth agent curl "https://as2.dotenvx.com/get?key=KEY,TWILIO"

Check if an email address is real before you hit send. Verifies syntax, DNS, MX records, SMTP mailbox existence, and cross-references multiple providers. All in real time, no signup required.

github.com/treadiehq/docle

# verify an email
vestauth agent curl https://docle.co/api/verify -d '{"emails":["test@example.com"]}'

# check your usage
vestauth agent curl https://docle.co/api/agent/usage

• Geo IP - coming soon
• Send/Receive Email - coming
• Send/Receive SMS - coming
• Send/Receive Telegram - coming
• Send/Receive WhatsApp - coming
• Human-in-the-loop - coming
• Rotate NPM Tokens - coming
• Rotate GitHub Tokens - coming
• Working on a tool? Tell us and we'll list it.

Authentication

Build your own tools. Authenticate them with a single line of code – vestauth.tool.verify…

...
const vestauth = require('vestauth')

app.post('/whoami', async (req, res) => {
  try {
    const url = `${req.protocol}://${req.get('host')}${req.originalUrl}`
    const agent = await vestauth.tool.verify(req.method, url, req.headers)

    res.json(agent)
  } catch (err) {
    res.status(401).json({ code: 401, error: { message: err.message }})
  }
})
...

…the agents sign HTTP requests with a drop-in curl wrapper.

> SIGNED - 200
$ vestauth agent curl https://api.vestauth.com/whoami
{"uid":"agent-4b94ccd425e939fac5016b6b",...}

vestauth agent curl autosigns curl requests – injecting valid signed headers according to the web-bot-auth draft. You can peek these with the built-in headers primitive.

$ vestauth primitives 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"
}

Vestauth handles usage, payments, and spam protection for your tool!

Self-hosting

Run your own Vestauth server.

| | |---| | |

Initialize the server and run migrations (postgres).

$ curl -sSf https://vestauth.sh | sh
$ vestauth server init
$ vestauth server db:create
$ vestauth server db:migrate

Start the server.

$ vestauth server start
vestauth server listening on http://localhost:3000

And use your server's hostname when creating agents.

$ mkdir your-agent
$ cd your-agent

$ vestauth agent init --hostname http://localhost:3000
✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)

That's it. Your Vestauth (web-bot-auth) infrastructure is now running under your control.

More details

Edit the .env file to configure your server.

PORT="3000"
HOSTNAME="http://localhost:3000"
DATABASE_URL="postgres://localhost/vestauth_production"

For example, in production:

• Change HOSTNAME to its production url - e.g. vestauth.yoursite.com
• Change DATABASE_URL to a managed postgres - e.g. postgresql://USER:PASS@aws-1-us-east-1.pooler.supabase.com:5432/postgres

[!WARNING]

Production note: Configure a wildcard DNS record for *.${HOSTNAME}.

Example: if HOSTNAME=vestauth.yourapp.com, add *.vestauth.yourapp.com.

Required for .well-known discovery per the [web-bot-auth](https://datatracker.ietf.org/doc/html/draft