Configuration

Environment variables and configuration options for self-hosted Vestauth servers

Environment Variables

Vestauth server configuration is managed through environment variables stored in a .env file. Run vestauth server init to create this file automatically.

PORT

The port the server listens on.

• Default: 3000
• Type: String or Number
• Example: "3000" or "8080"

.env

PORT="3000"

You can override this when starting the server:

vestauth server start --port 4567

HOSTNAME

The full URL where your Vestauth server is accessible. This is critical for agent registration and discovery.

• Default: http://localhost:3000
• Type: String (URL)
• Local development: http://localhost:3000
• Production: https://vestauth.yoursite.com

.env (Development)

HOSTNAME="http://localhost:3000"

.env (Production)

HOSTNAME="https://vestauth.yoursite.com"

Critical for production: The HOSTNAME must match your actual server URL. Agents use this to construct their discovery endpoints.

For example, if HOSTNAME=https://vestauth.yoursite.com, agents will be discoverable at:

https://agent-{uid}.vestauth.yoursite.com/.well-known/http-message-signatures-directory

You can override this when starting the server:

vestauth server start --hostname https://vestauth.yoursite.com

DATABASE_URL

PostgreSQL connection string.

• Default: postgres://localhost/vestauth_production
• Type: String (PostgreSQL connection URL)
• Format: postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...]

.env (Local PostgreSQL)

DATABASE_URL="postgres://localhost/vestauth_production"

.env (Managed PostgreSQL)

DATABASE_URL="postgresql://USER:[e-mail]:5432/postgres"

The database URL is used by:

• vestauth server db:create - Creates the database
• vestauth server db:migrate - Runs migrations
• vestauth server start - Connects to the database

You can override this when starting the server:

vestauth server start --database-url postgresql://USER:PASS@host:5432/db

Configuration File

The .env file is created in your current directory when you run vestauth server init. Here’s a complete example:

.env

# [vestauth server start] self-hosted vestauth server
#
# Usage:
# $ vestauth server init --port=3001 --hostname="http://localhost:3001" --database-url="postgresql://USER:[e-mail]:5432/postgres"
#
# PORT: port the server listens on
# HOSTNAME: http://localhost:3000 in dev or https://vestauth.yoursite.com in prod
# DATABASE_URL: postgres://localhost/vestauth_production or a managed Postgres URL
#

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

Wildcard DNS Requirements

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

This is required for the web-bot-auth .well-known discovery specification.

Vestauth uses subdomain-based routing to serve agent public keys. Each agent gets a unique subdomain:

agent-{uid}.vestauth.yoursite.com

For this to work, you must configure DNS to route all subdomains to your server.

Example DNS Configuration

If your HOSTNAME=https://vestauth.yourapp.com, configure:

# Main domain (A record)
vestauth.yourapp.com. IN A 203.0.113.10

# Wildcard subdomain (A record)
*.vestauth.yourapp.com. IN A 203.0.113.10

Or using CNAME:

# Main domain (CNAME)
vestauth.yourapp.com. IN CNAME your-server.example.com.

# Wildcard subdomain (CNAME)
*.vestauth.yourapp.com. IN CNAME your-server.example.com.

Local Development

For local development with localhost, wildcard DNS works automatically:

http://agent-test.localhost:3000  ✓ Works
http://agent-abc.localhost:3000   ✓ Works

Testing Wildcard DNS

Verify your wildcard DNS is working:

# Should resolve to your server IP
dig agent-test.vestauth.yourapp.com

# Test with curl
curl http://agent-test.vestauth.yourapp.com

Production Configuration Checklist

1. Update HOSTNAME

   Change from http://localhost:3000 to your production domain:

   HOSTNAME="https://vestauth.yoursite.com"
   
2. Configure Wildcard DNS

   Add DNS record for *.vestauth.yoursite.com pointing to your server.

3. Use Managed PostgreSQL

   Update DATABASE_URL to a production database:

   DATABASE_URL="postgresql://USER:[e-mail]:5432/postgres"
   
4. Set Up HTTPS

   Configure SSL/TLS using:

   • Let’s Encrypt with Caddy (automatic HTTPS)
   • Nginx with certbot
   • Cloudflare proxy
   • Load balancer SSL termination
5. Configure Reverse Proxy

   Set up nginx or Caddy to forward requests to your server port:

   nginx.conf

   server {
     listen 443 ssl;
     server_name vestauth.yoursite.com *.vestauth.yoursite.com;
     
     location / {
       proxy_pass http://localhost:3000;
       proxy_set_header Host $host;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
     }
   }
   

Environment Variable Precedence

Vestauth resolves configuration in this order:

1. Command-line flags (highest priority)

   vestauth server start --port 4567
   

2. .env file

   PORT="3000"
   

3. Default values (lowest priority)

   • PORT: 3000
   • HOSTNAME: http://localhost:3000
   • DATABASE_URL: postgres://localhost/vestauth_production

Security Considerations

Protect your .env file: Never commit .env to version control. It contains database credentials and server configuration.

Add to .gitignore:

.env
.env.*

Database Security

• Use strong passwords for PostgreSQL
• Enable SSL for database connections in production
• Restrict database access to your server’s IP
• Use read-only credentials where possible

Network Security

• Always use HTTPS in production (not HTTP)
• Configure firewall rules to restrict access
• Use a reverse proxy (nginx, Caddy) for SSL termination
• Enable rate limiting to prevent abuse

Advanced Configuration

For advanced configuration options, you can modify the server code directly:

• Server implementation: src/server/index.js
• Database models: src/server/models/
• Express middleware: src/server/index.js (lines 23-61)