Documentation v1.0.0

Overview

The Laravel Hetzner Robot SDK provides a production-ready client interface for managing bare-metal servers, subnets, failover IPs, Wake on LAN systems, storage boxes, firewalls, and vSwitches. Compatible with PHP 8.2 through 8.5, and Laravel 11 through 13.

Installation

Install the package through Composer:

composer require ghostcompiler/laravel-hetzner-robot

Publish the configuration assets:

php artisan vendor:publish --provider="Vendor\HetznerRobot\Providers\HetznerRobotServiceProvider" --tag="config"

API Credentials

To use the Hetzner Robot API, you must generate a dedicated Web Service/App user. This separates your main account credentials from API access.

Configuration

The published configuration file lives at config/hetzner-robot.php. You can configure your Robot Web Service credentials in your .env file.

return [
    'username' => env('HETZNER_ROBOT_USERNAME'),
    'password' => env('HETZNER_ROBOT_PASSWORD'),
    'base_url' => env('HETZNER_ROBOT_BASE_URL', 'https://robot-ws.your-server.de'),
    'timeout' => (int) env('HETZNER_ROBOT_TIMEOUT', 30),
    'retries' => (int) env('HETZNER_ROBOT_RETRIES', 3),
    'retry_backoff' => (int) env('HETZNER_ROBOT_RETRY_BACKOFF', 100),
    'logging' => [
        'enabled' => (bool) env('HETZNER_ROBOT_LOGGING_ENABLED', false),
        'channel' => env('HETZNER_ROBOT_LOGGING_CHANNEL'),
    ],
];

Service Provider

The service provider binds the singleton client and orchestrator to Laravel's service container.

use Vendor\HetznerRobot\Managers\HetznerManager;

$manager = app(HetznerManager::class);
$servers = $manager->servers()->all();

Facades

Interact with the SDK fluently using the Facade accessor.

use Vendor\HetznerRobot\Facades\HetznerRobot;

$server = HetznerRobot::servers()->find(123456);

Servers

Manage bare-metal servers, update their names, and request cancellations.

// List all servers
$servers = HetznerRobot::servers()->all();

// Find a single server
$server = HetznerRobot::servers()->find(123456);

// Rename a server
$updatedServer = HetznerRobot::servers()->update(123456, [
    'server_name' => 'production-web-01'
]);

IP Addresses

Manage individual IP addresses, reverse DNS, and MAC configurations.

// List all IP addresses
$ips = HetznerRobot::ips()->all();

// Find a specific IP
$ip = HetznerRobot::ips()->find('123.123.123.123');

// Get MAC address configuration
$mac = HetznerRobot::ips()->getMac('123.123.123.123');

Subnets

Manage subnets, request MAC addresses, and handle cancellation policies.

// List all subnets
$subnets = HetznerRobot::subnets()->all();

// Find a specific subnet
$subnet = HetznerRobot::subnets()->find('2a01:4f8:123:456::/64');

Resets

View reset options and trigger hardware power cycles, manual restarts, or ACPI shutdowns.

// List resets for all servers
$resets = HetznerRobot::resets()->all();

// Trigger a hardware reset
$result = HetznerRobot::resets()->create(123456, [
    'type' => 'hw' // Options: hw, sw, man, power, acpi
]);

Failover IPs

Route highly available failover IP addresses dynamically to other target servers.

// List all failovers
$failovers = HetznerRobot::failovers()->all();

// Route failover IP to a new server IP
$failover = HetznerRobot::failovers()->update('138.201.12.34', '138.201.56.78');

Wake On LAN

Retrieve Wake on LAN configurations and send WoL magic packets to servers.

// Check Wake on LAN availability for a server
$wol = HetznerRobot::wols()->find(123456);

// Send WoL packet
$result = HetznerRobot::wols()->send(123456);

Boot Configurations

Configure rescue environments, install custom OS setups (Linux, Windows), or enable VNC consoles.

// Get boot settings
$boot = HetznerRobot::boots()->find(123456);

// Enable rescue system
$rescue = HetznerRobot::boots()->enableRescue(123456, [
    'os' => 'linux',
    'arch' => 64
]);

// Enable VNC installer
$vnc = HetznerRobot::boots()->enableVnc(123456, [
    'dist' => 'CentOS 9',
    'arch' => 64
]);

Reverse DNS

Manage reverse DNS (PTR) records for IP addresses and subnets.

// List PTR records
$rdns = HetznerRobot::rdns()->all();

// Find PTR for IP
$ptr = HetznerRobot::rdns()->find('123.123.123.123');

// Set/Update PTR record
$newPtr = HetznerRobot::rdns()->update('123.123.123.123', 'static.example.com');

Traffic Queries

Monitor bandwidth and traffic consumption details across servers, subnets, and failover IPs.

// Query traffic statistics
$traffic = HetznerRobot::traffic()->query([
    'type' => 'day', // day, month, year
    'from' => '2026-06-01',
    'to' => '2026-06-14',
    'ip' => ['123.123.123.123']
]);

SSH Keys

Manage SSH keys stored in your Robot account for automated rescue logins.

// List keys
$keys = HetznerRobot::sshKeys()->all();

// Create new SSH Key
$key = HetznerRobot::sshKeys()->create([
    'name' => 'admin-laptop',
    'data' => 'ssh-rsa AAAAB3NzaC1yc2E...'
]);

// Delete key
HetznerRobot::sshKeys()->delete('12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef');

Ordering

Retrieve order products and provision bare-metal servers, market servers, or addons.

// --- Standard Servers ---
// Get products catalog
$products = HetznerRobot::orders()->getServerProducts();

// Get order transactions
$transactions = HetznerRobot::orders()->getServerTransactions();

// Order a specific server product
$order = HetznerRobot::orders()->orderServer([
    'product_id' => 'EX44',
    'authorized_key' => '12:34:56:78...'
]);

// --- Server Market / Auction ---
// Get market/auction products catalog
$marketProducts = HetznerRobot::orders()->getMarketProducts();

// Get specific market server details
$marketProduct = HetznerRobot::orders()->getMarketProduct('3016304');

// Order a market auction server
$marketOrder = HetznerRobot::orders()->orderMarket([
    'product_id' => 3016304,
    'authorized_key' => ['12:34:56:78...'],
    'dist' => 'Rescue system',
    'lang' => 'en'
]);

// Get market order transactions
$marketTransactions = HetznerRobot::orders()->getMarketTransactions();

Storage Boxes

Manage Storage Boxes, update accounts, handle snapshots, snapshot plans, and sub-accounts.

// List Storage Boxes
$boxes = HetznerRobot::storageBoxes()->all();

// Find a specific storage box
$box = HetznerRobot::storageBoxes()->find(12345);

// Create box snapshot
$snapshot = HetznerRobot::storageBoxes()->createSnapshot(12345);

Firewalls

Configure hardware firewalls for bare-metal servers or work with reusable templates.

// Get server firewall config
$firewall = HetznerRobot::firewalls()->find(123456);

// Apply a template firewall rule set
$result = HetznerRobot::firewalls()->create(123456, [
    'status' => 'active',
    'filter_ipv4' => 'active',
    'rules' => [
        'input' => [
            ['ip_version' => 'ipv4', 'action' => 'accept', 'proto' => 'tcp', 'dst_port' => '80'],
            ['ip_version' => 'ipv4', 'action' => 'accept', 'proto' => 'tcp', 'dst_port' => '443']
        ]
    ]
]);

vSwitches

Setup virtual local networks (vSwitches) and assign or remove bare-metal servers.

// List vSwitches
$vswitches = HetznerRobot::vswitches()->all();

// Create a new vSwitch
$switch = HetznerRobot::vswitches()->create([
    'name' => 'backend-lan',
    'vlan' => 4000
]);

// Add servers to vSwitch
HetznerRobot::vswitches()->addServers($switchId, [123456, 123457]);

Async Requests

Configure queries asynchronously to yield Guzzle Promises.

$promise = HetznerRobot::servers()->async()->all();
$servers = $promise->wait();

Batch Operations

Run calls concurrently in pooled execution tasks.

$results = HetznerRobot::batch([
    fn () => HetznerRobot::servers()->find(123456),
    fn () => HetznerRobot::servers()->find(123457),
]);

Retries & Rate Limits

Request pipeline is governed by automatic Guzzle middleware.

Exception Handling

HTTP error codes automatically map to specific PHP exception classes.

try {
    HetznerRobot::servers()->find(999999);
} catch (\Vendor\HetznerRobot\Exceptions\NotFoundException $e) {
    // 404 Error
}

Helper Cheatsheet

Quick copy reference table for common helper methods.

FAQ