Deploy Warpgate on a VPS

Warpgate is a smart bastion host that proxies SSH, HTTPS, and MySQL/Postgres sessions through a single point of access with web-based session recording and RBAC, without requiring agents on target hosts.

Assumptions: Ubuntu 24.04 LTS RamNode VPS, a domain/hostname for the admin UI (e.g. bastion.example.com), root or sudo access.

1. Prerequisites

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl ufw ca-certificates

Decide up front which ports Warpgate will use (defaults):

• 22 or a custom port — SSH proxy
• 8888 — Web admin UI (HTTPS)
• 33066 — MySQL proxy (optional)
• 5432-range — Postgres proxy (optional)

If port 22 on the VPS is already used for direct sudo/admin SSH access, run Warpgate's SSH proxy on a different port (e.g. 2222) to avoid conflicts, or migrate host SSH to a non-standard port and let Warpgate own 22.

2. Install Warpgate

Option A: Prebuilt binary (simplest)

cd /tmp
curl -fsSL https://github.com/warp-tech/warpgate/releases/latest/download/warpgate-linux-x86_64.tar.gz -o warpgate.tar.gz
tar xzf warpgate.tar.gz
sudo mv warpgate /usr/local/bin/
sudo chmod +x /usr/local/bin/warpgate
warpgate --version

(Check https://github.com/warp-tech/warpgate/releases for the exact current asset name — it may be versioned differently.)

Option B: Docker

sudo mkdir -p /opt/warpgate/{data,config}
sudo docker pull ghcr.io/warp-tech/warpgate:latest

This guide continues with the native binary + systemd approach (Option A), since it plays more naturally with step-ca cert files and systemd.

3. Create a dedicated user and directories

sudo useradd -r -m -d /etc/warpgate -s /usr/sbin/nologin warpgate
sudo mkdir -p /etc/warpgate
sudo chown warpgate:warpgate /etc/warpgate

4. Generate initial config

cd /etc/warpgate
sudo -u warpgate warpgate init

This creates warpgate.yaml with sane defaults and a self-signed cert. Edit it:

sudo nano /etc/warpgate/warpgate.yaml

Key sections to review:

external_host: bastion.example.com

http:
  enable: true
  listen: 0.0.0.0:8888
  certificate: /etc/warpgate/tls/warpgate.crt
  key: /etc/warpgate/tls/warpgate.key

ssh:
  enable: true
  listen: 0.0.0.0:2222
  host_key_verification: strict

mysql:
  enable: false   # turn on only if you're proxying MySQL

database_url: sqlite:/etc/warpgate/db

5. Use step-ca for TLS instead of the self-signed cert (recommended)

If you've deployed step-ca (see the companion guide), issue a real internal cert:

sudo mkdir -p /etc/warpgate/tls
sudo -u warpgate step ca certificate "bastion.example.com" \
  /etc/warpgate/tls/warpgate.crt /etc/warpgate/tls/warpgate.key \
  --ca-url https://ca.internal.example.com:9000 \
  --root /etc/step-ca-root/root_ca.crt

Set up renewal via cron or step ca renew --daemon so the cert doesn't silently expire.

If you don't have step-ca, use Let's Encrypt via a reverse proxy (Caddy/nginx) in front of Warpgate's admin UI instead, terminating TLS there and proxying to 127.0.0.1:8888.

6. Create the initial admin account

sudo -u warpgate warpgate admin add-user \
  --username admin \
  --password

(You'll be prompted to set a password interactively. Alternatively use --credential-name for SSO/public-key setups — see Warpgate docs for OIDC integration if you want SSO login for the admin UI.)

7. Run Warpgate as a systemd service

sudo tee /etc/systemd/system/warpgate.service > /dev/null <<'EOF'
[Unit]
Description=Warpgate bastion host
After=network.target

[Service]
Type=simple
User=warpgate
Group=warpgate
WorkingDirectory=/etc/warpgate
ExecStart=/usr/local/bin/warpgate run
Restart=on-failure
RestartSec=5
AmbientCapabilities=CAP_NET_BIND_SERVICE
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now warpgate
sudo systemctl status warpgate

AmbientCapabilities=CAP_NET_BIND_SERVICE lets the non-root warpgate user bind to privileged ports (e.g. 22 or 443) if you choose to use them instead of the higher default ports.

8. Firewall

sudo ufw allow OpenSSH          # keep your existing admin SSH access safe
sudo ufw allow 2222/tcp         # Warpgate SSH proxy port (adjust to your chosen port)
sudo ufw allow 8888/tcp         # Warpgate admin UI / HTTPS proxy
# Only if using DB proxying:
# sudo ufw allow 33066/tcp
sudo ufw enable

Be careful not to lock yourself out — confirm your normal SSH session still works before closing your current connection.

9. Add targets (hosts/services to proxy)

Via the web admin UI at https://bastion.example.com:8888, or via CLI:

sudo -u warpgate warpgate admin add-target \
  --name "prod-web-01" \
  --kind ssh \
  --host 10.0.0.5 \
  --port 22

Then create roles and assign targets/users to roles so access is scoped per team/user.

10. Client usage

Users connect through Warpgate rather than directly to targets:

ssh -J admin@bastion.example.com:2222 target-user@prod-web-01

or, depending on Warpgate's ticket/target-alias model, directly:

ssh admin#prod-web-01@bastion.example.com -p 2222

(Exact syntax depends on your configured target aliases — check the admin UI's "connection instructions" panel per target, which Warpgate generates for you.)

11. Session recording review

Recorded sessions are viewable in the admin web UI under "Sessions." Storage grows over time — monitor disk usage on /etc/warpgate (or wherever database_url and recording paths point) and set a retention/cleanup policy.

12. Updating

sudo systemctl stop warpgate
curl -fsSL https://github.com/warp-tech/warpgate/releases/latest/download/warpgate-linux-x86_64.tar.gz -o /tmp/warpgate.tar.gz
tar xzf /tmp/warpgate.tar.gz -C /tmp
sudo mv /tmp/warpgate /usr/local/bin/warpgate
sudo systemctl start warpgate

13. Troubleshooting