Server Commands

Self-host your own Vestauth infrastructure

Overview

Server commands let you run your own Vestauth server with full control over your agent identity infrastructure.

Self-hosting is optional. You can use api.vestauth.com without running your own server.

Prerequisites

• PostgreSQL database
• Node.js 18+ or standalone binary

Quick Start

# Initialize server configuration
vestauth server init

# Create database
vestauth server db:create

# Run migrations
vestauth server db:migrate

# Start server
vestauth server start

---

server init

Create or update the server .env configuration file.

vestauth server init

Output:

✔ ready (.env/HOSTNAME=http://localhost:3000)
⮕ next run: [vestauth server start]

Options

--port · string · default: "3000"

Server port. Defaults to PORT environment variable, then 3000.

--hostname · string · default: "http://localhost:3000"

Server hostname (including scheme). Defaults to HOSTNAME environment variable, then http://localhost:3000.

In production, use your public domain (e.g., https://vestauth.yoursite.com).

--database-url · string · default: "postgres://localhost/vestauth_production"

PostgreSQL connection string. Defaults to DATABASE_URL environment variable.

Format: postgresql://USER:PASS@HOST:PORT/DATABASE

Examples

Default (Local)

vestauth server init

Generated Configuration

Creates a .env file:

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

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 spec.

---

server start

Start the Vestauth server.

vestauth server start

Output:

vestauth server listening on http://localhost:3000

Options

--port · string

Override server port. Defaults to PORT from .env.

--hostname · string

Override server hostname. Defaults to HOSTNAME from .env.

--database-url · string · default: "postgres://localhost/vestauth_production"

Override database connection string. Defaults to DATABASE_URL from .env.

Examples

Default

vestauth server start

Server Endpoints

The server provides these endpoints:

Endpoint	Purpose
POST /agents	Register new agent
PUT /agents/:uid/keys	Rotate agent keys
GET /:uid.{hostname}/.well-known/http-message-signatures-directory	Public key discovery
/whoami	Verify agent identity

Production Deployment

For production:

1. Use a managed PostgreSQL database
2. Set HOSTNAME to your public domain
3. Configure wildcard DNS (*.vestauth.yoursite.com)
4. Use a process manager (PM2, systemd, etc.)
5. Enable HTTPS via reverse proxy (nginx, Caddy)

PM2

pm2 start vestauth -- server start
pm2 save
pm2 startup

---

server db:create

Create the vestauth_production PostgreSQL database.

vestauth server db:create

Output:

Created database 'vestauth_production'

Options

--database-url · string · default: "postgres://localhost/vestauth_production"

PostgreSQL connection string. Defaults to DATABASE_URL from .env.

Examples

Default

vestauth server db:create

Requires PostgreSQL to be running and the user to have CREATEDB privileges.

---

server db:migrate

Run database migrations to create the required schema.

vestauth server db:migrate

Output:

== 20260223204000 CreateAgentsTable: migrating ================================================
== 20260223204000 CreateAgentsTable: migrated (0.0160s) ===========================
== 20260223205500 CreatePublicJwksTable: migrating ================================================
== 20260223205500 CreatePublicJwksTable: migrated (0.0100s) ===========================

Options

--database-url · string · default: "postgres://localhost/vestauth_production"

PostgreSQL connection string. Defaults to DATABASE_URL from .env.

Database Schema

Creates these tables:

agents

• uid - Unique agent identifier
• created_at - Agent creation timestamp
• updated_at - Last update timestamp

public_jwks

• kid - Key ID
• agent_uid - Associated agent UID
• jwk - Public key (JSON Web Key)
• created_at - Key creation timestamp
• revoked_at - Key revocation timestamp (if revoked)

Running Migrations

Initial Setup

vestauth server db:migrate

Migrations are idempotent. Running them multiple times is safe.

---

server db:drop

Delete the vestauth_production database.

vestauth server db:drop

Output:

Dropped database 'vestauth_production'

Options

--database-url · string · default: "postgres://localhost/vestauth_production"

PostgreSQL connection string. Defaults to DATABASE_URL from .env.

This permanently deletes all agent data. Use with caution.

In production, use database backups instead of dropping the database.

When to Use

• Development: Reset local database
• Testing: Clean slate between test runs
• Migration testing: Verify migrations work on fresh database

Never use in production.

---

Environment Variables

Server commands read these from .env:

Variable	Description	Default
PORT	Server port	3000
HOSTNAME	Server hostname with scheme	http://localhost:3000
DATABASE_URL	PostgreSQL connection string	postgres://localhost/vestauth_production

Complete Setup Example

Here’s a full self-hosting workflow:

# 1. Install Vestauth
curl -sfS https://vestauth.sh | sh

# 2. Initialize server
vestauth server init \
  --hostname https://vestauth.yoursite.com \
  --database-url postgresql://user:[e-mail]:5432/vestauth

# 3. Create database
vestauth server db:create

# 4. Run migrations
vestauth server db:migrate

# 5. Start server
vestauth server start

Then create agents pointing to your server:

vestauth agent init --hostname https://vestauth.yoursite.com

Troubleshooting

Database Connection Failed

# Test connection
psql "$DATABASE_URL"

# Check PostgreSQL is running
pg_isready

Port Already in Use

# Use different port
vestauth server start --port 3001

# Or kill process using port 3000
lsof -ti:3000 | xargs kill

Migrations Failed

# Drop and recreate
vestauth server db:drop
vestauth server db:create
vestauth server db:migrate

Related

• Agent Commands - Create agents using your server
• Development Guide - Contributing to Vestauth