RamNode logo
    Sign UpLogin
    Deployment Guides
    Beginner
    15–20 min
    512 MB+ RAM

    Deploy Holesail on a RamNode VPS

    Encrypted peer-to-peer tunneling built on Hypercore DHT. Expose any local port to the internet without opening firewall rules, configuring port forwarding, or maintaining a static IP.

    What Is Holesail?

    Holesail is a peer-to-peer reverse proxy and network tunneling tool that lets you expose any local port to the internet without touching firewall rules, configuring port forwarding, or maintaining a static IP. It works over an encrypted P2P connection built on the Hypercore DHT, which means once it is running on your VPS, anyone with the connection key can reach your tunneled service from anywhere in the world.

    Expose a local dev server to a client or teammate without a domain
    Tunnel SSH access behind NAT or restrictive firewalls
    Share a self-hosted web app or game server via a single connection string
    Give temporary access to a VPS service without opening ports in UFW

    Prerequisites

    • A RamNode VPS running Ubuntu 22.04 LTS or Debian 12 (any plan with at least 512 MB RAM)
    • Root or sudo access
    • A non-root user is recommended for running Holesail as a service
    • Basic familiarity with SSH and the Linux command line
    1

    Update the System

    Log in as root or a sudo user and run a full package update before installing anything:

    Update system packages
    apt update && apt upgrade -y
    2

    Install Node.js via NVM

    Holesail requires Node.js 16 or newer. The recommended approach is NVM (Node Version Manager).

    Install NVM
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
    Load NVM into current session
    export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

    Confirm NVM is in your ~/.bashrc:

    Verify bashrc
    grep -n "NVM_DIR" ~/.bashrc
    Install Node.js 20 LTS
    nvm install 20
nvm use 20
nvm alias default 20
    Verify installation
    node -v
npm -v
    Expected output
    v20.x.x
10.x.x
    3

    Install Holesail

    Install Holesail globally
    sudo npm i holesail -g
    Verify the installation
    holesail --help

    Note: On some systems, sudo npm may not find the NVM-managed Node binary. If you get a command not found error, run npm i holesail -g without sudo, then add the global npm bin directory to your PATH.

    4

    Start a Holesail Tunnel

    Private Mode (Default)

    Private mode generates a connection key that is not discoverable on the DHT. Only someone with the exact key can connect.

    Expose port 3000
    holesail --live 3000
    Example output
    hs://s000a19f5778ccf3b7471fd45205758ad44a572aec1e7cdf76864613db0e63b8a49c

    Keep this key secure. Anyone with it can connect to your tunneled port.

    Public Mode

    Announces the tunnel on the DHT with a shorter, shareable key:

    Expose port 3000 publicly
    holesail --live 3000 --public

    Custom Connection Key

    Use a custom key
    holesail --live 3000 --key "my-custom-key-string"

    If the key is shorter than 32 characters, pass the --force flag:

    Short key with force flag
    holesail --live 3000 --key "short-key" --force

    Binding to a Specific Host

    By default, Holesail binds to 127.0.0.1. To expose a different interface:

    Bind to specific host
    holesail --live 3000 --host 192.168.1.100
    5

    Run Holesail as a Persistent systemd Service

    For production use, run Holesail as a systemd service so it survives reboots and reconnects automatically.

    Find the Holesail binary path
    which holesail
    Expected output
    /root/.nvm/versions/node/v20.19.0/bin/holesail

    Create the systemd unit file. Replace <PORT> with the port you want to expose and update ExecStart with the full path from above:

    /etc/systemd/system/holesail.service
    [Unit]
Description=Holesail P2P Tunnel
After=network.target

[Service]
Type=simple
User=root
ExecStart=/root/.nvm/versions/node/v20.19.0/bin/holesail --live <PORT>
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
    Enable and start
    systemctl daemon-reload
systemctl enable holesail
systemctl start holesail
    Check status and view connection key
    systemctl status holesail
journalctl -u holesail -n 50 --no-pager

    Stable key across reboots: Without a --key flag, a VPS reboot will produce a new connection string. Add a fixed key to your ExecStart:

    Fixed key in ExecStart
    ExecStart=/root/.nvm/versions/node/v20.19.0/bin/holesail --live <PORT> --key "your-stable-key-32chars-minimum"
    6

    Connect from a Client

    On the machine that needs to reach your VPS service, install Holesail the same way (Node.js + npm). Then run:

    Connect using the key
    holesail hs://s000a19f5778ccf3b7471fd45205758ad44a572aec1e7cdf76864613db0e63b8a49c

    This binds a local port (default 8989) on the client machine that proxies through to the exposed port on your VPS. Access the service at 127.0.0.1:8989.

    Custom local port
    holesail <KEY> --port 8080
    Bind to all interfaces
    holesail <KEY> --port 8080 --host 0.0.0.0

    Practical Examples

    SSH Tunneling

    Expose SSH (port 22) from your VPS through Holesail and access it from anywhere, even if port 22 is blocked by the client's network:

    On the VPS:

    Expose SSH
    holesail --live 22 --key "my-ssh-tunnel"

    On the client:

    Connect tunnel and SSH
    holesail "my-ssh-tunnel" --port 2222
ssh -p 2222 user@127.0.0.1

    Exposing a Web App

    Share a web app running on port 8080 temporarily with a colleague:

    Share web app
    holesail --live 8080 --public

    They run holesail <KEY> on their machine and hit http://127.0.0.1:8989 in their browser.

    Firewall Notes

    Holesail does not require any inbound ports to be open. Outbound UDP traffic is used for DHT peer discovery, and all tunnel traffic is encrypted end-to-end.

    If your VPS has a UFW ruleset that blocks all outbound traffic by default (uncommon but possible), allow outbound UDP:

    Allow outbound UDP
    ufw allow out proto udp to any

    For most RamNode VPS configurations with default UFW settings, Holesail works without any additional firewall changes.

    Security Considerations

    • Keep connection keys private. Anyone with a private-mode connection key can reach the tunneled port. Treat these like passwords.
    • Holesail does not replace application-level auth. If the service behind the tunnel has no authentication of its own, restrict access at the application layer before sharing the key.
    • Public mode is more discoverable. Prefer private mode (the default) for sensitive services.
    • Rotate keys periodically for long-lived tunnels by restarting the service with a new --key value.
    • Use a dedicated non-root user for the systemd service when running in production.

    Troubleshooting

    Holesail starts but the client cannot connect

    Check that the service is actually running and that the correct connection string is being used:

    Check service
    systemctl status holesail
journalctl -u holesail -n 100

    "holesail: command not found" after install

    The NVM bin directory may not be in the PATH for the current session. Source your bashrc:

    Fix PATH
    source ~/.bashrc

    Connection key changes on every restart

    Add a --key flag to the ExecStart in your unit file and reload the service.

    High CPU or memory use

    Check for multiple service instances running simultaneously:

    Check for stray processes
    ps aux | grep holesail
    More Deployment Guides•View Cloud VPS Plans