Hetzner Robot API Rhai Client & Local VM Orchestrator

This project provides two core functionalities:

1. A Rhai scripting client to programmatically manage Hetzner dedicated servers via the Robot API.
2. A local VM orchestrator (alpine-boot.sh) to quickly set up and run a lightweight Alpine Linux virtual machine on any host, ideal for development and testing.

This allows you to use the Rhai scripts to order a new server from Hetzner, and then use the alpine-boot.sh script on that new server to stand up a local virtualized environment.

1. Hetzner Rhai Client

The primary goal of this component is to offer a flexible and scriptable interface to the Hetzner Robot API, enabling automation of server management tasks. By leveraging Rhai, users can write simple yet powerful scripts to interact with their Hetzner infrastructure.

Rhai Examples

The examples/ directory contains several Rhai scripts demonstrating the capabilities of this client:

• examples/server_management.rhai: Showcases basic server management operations.
• examples/ssh_key_management.rhai: Demonstrates how to manage SSH keys.
• examples/boot_management.rhai: Provides examples for managing server boot configurations.
• examples/server_ordering.rhai: Contains comprehensive examples for ordering new servers and addons.

2. Local VM Setup with alpine-boot.sh

For local development and testing, this project includes a script to quickly boot a lightweight Alpine Linux virtual machine using cloud-hypervisor and virtiofs. The alpine-boot.sh script automates the entire process, from downloading the OS to configuring and launching the VM.

Prerequisites

On a fresh Debian-based system (like an Ubuntu server ordered from Hetzner), you must first install the required dependencies. These commands only need to be run once.

# Install dependencies from apt
sudo apt update && sudo apt install -y curl tar virtiofsd

# Download and install a static cloud-hypervisor binary
wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v47.0/cloud-hypervisor-static
chmod +x cloud-hypervisor-static
sudo ln -s "$(pwd)/cloud-hypervisor-static" /usr/local/bin/cloud-hypervisor

Note: The cloud-hypervisor version is pinned for stability.

Script Usage

Basic Boot

To download all assets and boot the VM with default settings (hostname alpine-3.22, root password root):

./alpine-boot.sh

Customizing the VM

You can customize the VM using command-line options:

• --hostname <name>: Set a custom hostname.
• --root-password <password>: Set a custom root password.

Example:

./alpine-boot.sh --hostname my-alpine --root-password mysecretpassword

Other Commands

• download-only: Downloads assets without booting.
• clean: Removes the workspace and all downloaded files.
• help: Displays the help message.

Important Note on IPv6 Addresses

When ordering a Hetzner server without an IPv4 addon, it might be assigned an IPv6 network like 2a01:4f8:221:1fe3::/64. You cannot directly SSH to this network address. Hetzner does not use SLAAC for server assignments. The actual address to SSH to will typically be the network address with 2 appended (e.g., 2a01:4f8:221:1fe3::2).