Add your server
Vessl runs your apps on servers you own. This guide walks through connecting a VPS to your Vessl account — a one-time setup per server.
What you need
- A VPS running Ubuntu. Vessl's provisioning only supports Ubuntu at this time.
- SSH access to the server — either root or a user with sudo privileges.
- The server's IP address and SSH port (default:
22).
Any reputable VPS provider works — Hetzner, Contabo, DigitalOcean, Biznet Gio, Niagahoster, and others.
Step 1 — Add an SSH key
Before adding a server, Vessl needs an SSH key it can use to connect. Go to Settings → SSH Keys and choose one of three options:
Option A: Auto-setup (recommended for most users) Enter your server's IP, port, SSH user, and current root password. Vessl connects once to install its own key, then never needs the password again.
Option B: Generate a new key
Vessl generates an ED25519 key pair. Download the private key immediately — it won't be shown again. Then add the public key to your server's ~/.ssh/authorized_keys manually.
Option C: Paste an existing public key
If you already have a key pair, paste the public key. You'll need to add it to authorized_keys on the server yourself. Note: manually-pasted keys can't be used for server provisioning (Vessl doesn't hold the private key), but they work for other SSH-based features.
Step 2 — Connect the server
Go to Servers → Connect Server. The wizard has two steps:
Step 1 of 2 — Identity
Fill in:
- Name — a label for this server (e.g.
production-vps-1) - Description — optional note
- IP Address — the server's public IP
- SSH User — defaults to
root; change this if you're using a non-root user - SSH Port — defaults to
22
Step 2 of 2 — SSH Key
Pick the SSH key Vessl should use to connect. Only keys stored in Vessl's key wallet appear here (not manually-pasted public keys, since Vessl doesn't hold those private keys).
You can optionally run Check Reachability to verify the SSH port is open, or Verify SSH Credentials to confirm the key actually authenticates — both are optional before clicking Start Provisioning.
Step 3 — Provisioning
Once you click Start Provisioning, Vessl connects to your server over SSH and sets it up automatically. You can watch the progress in real time. The phases are:
| Phase | What's happening |
|---|---|
| Checking Host Readiness | Verifies OS compatibility (Ubuntu), disk space, open ports |
| Preparing Host | Updates system packages, installs prerequisites |
| Installing Docker | Installs Docker Engine |
| Validating Docker | Confirms Docker is running correctly |
| Preparing Runtime | Sets up Vessl's internal network and volume structure |
| Converging Skeleton | Installs core Vessl services |
| Converging Gateway | Deploys Traefik as the HTTPS gateway |
| Verifying Runtime | Final health check across all components |
| Ready | Server is live and ready to accept app deploys |
Provisioning typically takes 3–8 minutes on a fresh VPS. When it completes, the server shows Active in your dashboard.
Provisioning doesn't touch your existing data or running processes. It only installs what Vessl needs (Docker, Traefik, and supporting services) on top of your existing OS.
Check the provisioning logs for the specific error. Common causes: the SSH key isn't added to authorized_keys, the server is behind a firewall blocking port 22, or the OS isn't Ubuntu. Fix the issue and retry — provisioning is idempotent.
After provisioning
Once the server is active, you can:
- Deploy apps to it from the app creation wizard
- Manage firewall rules from the server's Security tab (Starter and Pro)
- View metrics (CPU, memory, disk) from the server's Metrics tab
- Add more servers if your plan allows it
One server can host as many apps as its resources allow. You don't need a separate server per app.