Genesis Docs

Install / Hosting

DigitalOcean

Run a persistent Genesis Gateway on a DigitalOcean Droplet.

Prerequisites

  • DigitalOcean account (signup)
  • SSH key pair (or willingness to use password auth)
  • About 20 minutes

Setup

Create a Droplet

Use a clean base image (Ubuntu 24.04 LTS). Avoid third-party Marketplace 1-click images unless you have reviewed their startup scripts and firewall defaults.

  1. Log into DigitalOcean.
  2. Click Create > Droplets.
  3. Choose:
    • Region: Closest to you
    • Image: Ubuntu 24.04 LTS
    • Size: Basic, Regular, 1 vCPU / 1 GB RAM / 25 GB SSD
    • Authentication: SSH key (recommended) or password
  4. Click Create Droplet and note the IP address.

Connect and install

ssh root@YOUR_DROPLET_IP

apt update && apt upgrade -y

# Install Node.js 24
curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt install -y nodejs

# Install Genesis
curl -fsSL https://genesis.pixelzx.com/install.sh | bash
genesis --version

Run onboarding

genesis onboard --install-daemon

The wizard walks you through model auth, channel setup, gateway token generation, and daemon installation (systemd).

fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

Verify the gateway

genesis status
systemctl --user status genesis-gateway.service
journalctl --user -u genesis-gateway.service -f

Access the Control UI

The gateway binds to loopback by default. Pick one of these options.

Option A: SSH tunnel (simplest)

# From your local machine
ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP

Then open http://localhost:18789.

Option B: Tailscale Serve

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
genesis config set gateway.tailscale.mode serve
genesis gateway restart

Then open https://<magicdns>/ from any device on your tailnet.

Option C: Tailnet bind (no Serve)

genesis config set gateway.bind tailnet
genesis gateway restart

Then open http://<tailscale-ip>:18789 (token required).

Troubleshooting

Gateway will not start -- Run genesis doctor --non-interactive and check logs with journalctl --user -u genesis-gateway.service -n 50.

Port already in use -- Run lsof -i :18789 to find the process, then stop it.

Out of memory -- Verify swap is active with free -h. If still hitting OOM, use API-based models (Claude, GPT) rather than local models, or upgrade to a 2 GB Droplet.

Next steps