Genesis Docs

Install / Hosting

Oracle Cloud

Run a persistent Genesis Gateway on Oracle Cloud's Always Free ARM tier (up to 4 OCPU, 24 GB RAM, 200 GB storage) at no cost.

Prerequisites

Setup

Create an OCI instance

  1. Log into Oracle Cloud Console.
  2. Navigate to Compute > Instances > Create Instance.
  3. Configure:
    • Name: genesis
    • Image: Ubuntu 24.04 (aarch64)
    • Shape: VM.Standard.A1.Flex (Ampere ARM)
    • OCPUs: 2 (or up to 4)
    • Memory: 12 GB (or up to 24 GB)
    • Boot volume: 50 GB (up to 200 GB free)
    • SSH key: Add your public key
  4. Click Create and note the public IP address.

If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited.

Connect and update the system

ssh ubuntu@YOUR_PUBLIC_IP

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential

build-essential is required for ARM compilation of some dependencies.

Configure user and hostname

sudo hostnamectl set-hostname genesis
sudo passwd ubuntu
sudo loginctl enable-linger ubuntu

Enabling linger keeps user services running after logout.

Install Tailscale

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --ssh --hostname=genesis

From now on, connect via Tailscale: ssh ubuntu@genesis.

Install Genesis

curl -fsSL https://genesis.pixelzx.com/install.sh | bash
source ~/.bashrc

When prompted "How do you want to hatch your bot?", select Do this later.

Configure the gateway

Use token auth with Tailscale Serve for secure remote access.

genesis config set gateway.bind loopback
genesis config set gateway.auth.mode token
genesis doctor --generate-gateway-token
genesis config set gateway.tailscale.mode serve
genesis config set gateway.trustedProxies '["127.0.0.1"]'

systemctl --user restart genesis-gateway.service

gateway.trustedProxies=["127.0.0.1"] here is only for the local Tailscale Serve proxy's forwarded-IP/local-client handling. It is not gateway.auth.mode: "trusted-proxy". Diff viewer routes keep fail-closed behavior in this setup: raw 127.0.0.1 viewer requests without forwarded proxy headers can return Diff not found. Use mode=file / mode=both for attachments, or intentionally enable remote viewers and set plugins.entries.diffs.config.viewerBaseUrl (or pass a proxy baseUrl) if you need shareable viewer links.

Lock down VCN security

Block all traffic except Tailscale at the network edge:

  1. Go to Networking > Virtual Cloud Networks in the OCI Console.
  2. Click your VCN, then Security Lists > Default Security List.
  3. Remove all ingress rules except 0.0.0.0/0 UDP 41641 (Tailscale).
  4. Keep default egress rules (allow all outbound).

This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. You can only connect via Tailscale from this point on.

Verify

genesis --version
systemctl --user status genesis-gateway.service
tailscale serve status
curl http://localhost:18789

Access the Control UI from any device on your tailnet:

https://genesis.<tailnet-name>.ts.net/

Replace <tailnet-name> with your tailnet name (visible in tailscale status).

Fallback: SSH tunnel

If Tailscale Serve is not working, use an SSH tunnel from your local machine:

ssh -L 18789:127.0.0.1:18789 ubuntu@genesis

Then open http://localhost:18789.

Troubleshooting

Instance creation fails ("Out of capacity") -- Free tier ARM instances are popular. Try a different availability domain or retry during off-peak hours.

Tailscale will not connect -- Run sudo tailscale up --ssh --hostname=genesis --reset to re-authenticate.

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

ARM binary issues -- Most npm packages work on ARM64. For native binaries, look for linux-arm64 or aarch64 releases. Verify architecture with uname -m.

Next steps