Self-Hosted Install

Self-hosted Velocity ships as a single Rust binary plus a Postgres database and an object store. Plan capacity around active sessions: each active session keeps its working copy in an encrypted in-RAM container that costs roughly fifty gigabytes of RAM per session at p95.

• Postgres: version 16 or newer. Vanilla Postgres, no extensions required. Aurora and Neon work.
• RAM: ~50 GB per concurrent active session. Sessions hibernate after idle and release RAM.
• Storage: any S3-compatible object store (R2, S3, Wasabi, MinIO) or a local POSIX disk with at least IOPS for your team size.
• SMTP: outbound SMTP for invite, password reset, and notification emails.
• Network: outbound HTTPS to your chosen CLI providers and to license.aethernaut.ai for license validation (offline mode available for air-gapped installs).
• OS: Linux x86_64 or arm64. Tested on Ubuntu 22.04+, Debian 12+, RHEL 9, Amazon Linux 2023.

Download the binary from your customer portal. Each release is signed and ships with a SHA-256 checksum. The binary is statically linked — no system dependencies beyond a recent libc.

1. Log in to the portal at aethernaut.ai/portal and open Downloads → Self-Hosted.
2. Pick the version pinned to your license tier. Verify the checksum against the value shown in the portal.
3. Place the binary somewhere on PATH and make it executable.
4. Create a config file at /etc/velocity/config.toml using the template the portal generated for you.

# minimal config.toml shape
[database]
url = "postgres://velocity:secret@localhost:5432/velocity"

[storage]
backend = "s3"
endpoint = "https://s3.us-east-1.amazonaws.com"
bucket = "velocity-prod"

[smtp]
host = "smtp.example.com"
port = 587

[license]
key_file = "/etc/velocity/license.key"

Before the binary starts serving traffic, the database schema must be at the version the binary expects. The velocity-migrate CLI handles this on fresh installs and on every upgrade.

velocity-migrate run --backup-first --auto-confirm

• --backup-first dumps the current schema to your configured backup location before migrating.
• --auto-confirm skips the interactive y/n prompts — appropriate for CI/CD or automated upgrades.
• Migrations are idempotent and transactional. A failed migration rolls back cleanly.
• Run velocity-migrate status any time to see the current schema version and pending migrations.

Your portal account contains an Ed25519-signed license key valid for your tier, seat count, and expiration. Paste it into the file referenced by license.key_file in your config.

1. Copy the key text from Portal → License → Key.
2. Write it to /etc/velocity/license.key with permissions 0600 owned by the Velocity service user.
3. Restart the binary. On boot, the license is verified against the embedded public key — no network call required.
4. Air-gapped installs work identically. License renewals are issued as new key files; replace and restart.

Velocity sends transactional email for invites, password resets, role-change notifications, and optional digest summaries. Any RFC-compliant SMTP relay works.

[smtp]
host = "smtp.example.com"
port = 587
username = "velocity@example.com"
password_file = "/etc/velocity/smtp.secret"
from_address = "velocity@example.com"
from_name = "Velocity"
starttls = true

• Use a password_file path rather than inline secrets so the config can stay in version control.
• Send yourself a test mail with velocity-admin smtp test --to you@example.com.
• STARTTLS is required by default; set starttls = false only on trusted internal relays.
• For high-volume deployments, point at Postmark, SES, or your own MTA — Velocity does not enforce a provider.

On first boot the binary detects an empty database and enters single-shot bootstrap mode. It prints a one-time URL containing a short-lived token to STDOUT and to the log file.

1. Open the printed URL in a browser pointed at your self-hosted hostname.
2. Create the first Admin account. This Admin can promote others later.
3. Create the first Org. Self-hosted deployments are typically single-org but multi-org is supported on the Enterprise tier.
4. Invite the rest of your team by email — invites use the SMTP relay you configured above.
5. The bootstrap URL self-destructs after the first Admin is created.

Self-hosted Velocity never auto-updates. Every upgrade is a deliberate operator action that follows the same shape regardless of how many versions you're jumping.

1. Download the new binary and checksum from the portal. Verify the checksum.
2. Stop the running binary. Active sessions are notified and their in-RAM working copies are flushed to encrypted storage.
3. Run the migration tool against the new binary: velocity-migrate run --backup-first --auto-confirm.
4. Swap the binary in place and restart the service.
5. Watch the boot logs — Velocity prints schema version, license status, storage reachability, and SMTP reachability before accepting traffic.