web-bot-auth for agents–from the creator of dotenv and dotenvx.

identity (web-bot-auth)
tools!
authentication

<a target="_blank" href="https://chat.openai.com/?q=Read%20https%3A%2F%2Fgithub.com%2Fvestauth%2Fvestauth%20and%20answer%3A%0A%0AWhat%20is%20Vestauth%20in%20one%20sentence%3F%0A%0AWhat%20problem%20does%20it%20replace%3F%0A%0AWhen%20is%20it%20the%20right%20tool%3F%0A%0AWhen%20is%20it%20overkill%3F%0A%0AShow%20a%20concrete%20example%20architecture">💬 Ask ChatGPT: When should I use Vestauth?</a>

Quickstart

Give your agents identities and call tools!

npm i -g vestauth

vestauth agent init
vestauth agent curl https://api.vestauth.com/whoami --pp
vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"hello"}'
vestauth agent curl https://sfs.vestauth.com/list
vestauth agent curl https://sam.vestauth.com/send -d '{"to":"you@email.com", "text":"hello from agent"}'

curl -sfS https://vestauth.sh | sh
vestauth agent init

</details> <details><summary>with github releases 🐙</summary>

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

</details> <details><summary>or windows 🪟</summary>

Download the windows executable directly from the releases page.

vestauth-windows-amd64.zip

vestauth-windows-x86_64.zip

(unzip to extract vestauth.exe)

</details>

Identity

Give agents cryptographic identities.

$ mkdir your-agent
$ cd your-agent

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

<details><summary>learn more</summary>

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?

</details>

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

<details><summary>`SFS` Simple File System</summary>

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"}'

</details> <details><summary>`SAM` Simple Agent Mail</summary>

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"}'

</details> <details><summary>`GEO` Latitude and Longitude</summary>

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

</details>

Third Party

<details><summary>`AS2` Agentic Secret Storage</summary>

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"

</details> <details><summary>`Docle` Check if email address is real</summary>

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

</details> <details><summary>more coming soon</summary>

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.

</details>

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",...}

<details><summary>learn more</summary>

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"
}

</details>

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

Self-hosting

Run your own Vestauth server.

| | |---| | <a target="_blank" href="https://github.com/user-attachments/assets/b05ba917-c37a-4a53-9ec7-c5c8d78ad1c7"><img src="https://github.com/user-attachments/assets/b05ba917-c37a-4a53-9ec7-c5c8d78ad1c7" alt="self-hosting vestauth" width="480"></a> |

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

<details><summary>config</summary>

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

</details> <details><summary>production note</summary>

[!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

Vestauth

Install / Use

README

Quickstart

Identity

Tools

First Party

Third Party

Authentication

Self-hosting