A Go-based CLI tool for managing ephemeral Hetzner Cloud servers with automatic DNS management, SSL provisioning, and SSH alias setup.

• 🚀 One-command server creation: hcbox up romulus1
• 🗑️ One-command server deletion: hcbox down romulus1
• 🌐 Automatic DNS management via Cloudflare
• 🔒 Automatic SSL certificates via Caddy
• 🔑 SSH alias management for easy access
• ⚡ Fast and reliable server lifecycle management

Using Homebrew:

brew tap reckerp/tap
brew install hcbox

Using go install:

go install github.com/reckerp/hcbox@latest

1. Go 1.24+ installed on your system
2. Hetzner Cloud account with API token
3. Cloudflare account with API token and DNS zone
4. SSH key pair added to Hetzner Cloud

git clone https://github.com/reckerp/hcbox.git
cd hcbox
go build -o hcbox
sudo mv hcbox /usr/local/bin/

1. Create the configuration directory:

mkdir -p ~/.config/hcbox

2. Copy the example configuration:

cp config.yaml.example ~/.config/hcbox/config.yaml

3. Edit the configuration file with your credentials:

# Hetzner Cloud Configuration
hetzner:
  token: "your-hetzner-api-token"
  ssh_key_name: "my-key-name"
  location: "fsn1"
  image: "ubuntu-22.04"
  server_type: "cx21"

# Cloudflare Configuration
cloudflare:
  token: "your-cloudflare-api-token"
  zone: "example.com"

# SSH Configuration
ssh:
  # Use SSH agent (set to true for 1Password SSH agent)
  use_agent: true
  # Path to your private SSH key (only needed if use_agent is false)
  key_path: "~/.ssh/id_rsa"

1. Hetzner Cloud API Token: Create a token in your Hetzner Cloud Console
2. SSH Key: Add your public SSH key to Hetzner Cloud and note the key name
3. Cloudflare API Token: Create a token with DNS edit permissions for your zone
4. DNS Zone: Ensure you have a Cloudflare-managed DNS zone

hcbox supports flexible domain naming with optional prefixes:

• With prefix: server1.dev.example.com (if prefix: "dev")
• Without prefix: server1.example.com (if no prefix specified)
• Customizable: Change the prefix in config to organize servers

hcbox supports SSH agents (like 1Password SSH agent) for enhanced security:

• Set use_agent: true in your config to use SSH agent
• When using SSH agent, no key_path is required
• SSH aliases will be created without IdentityFile directive
• The system will use available keys from your SSH agent

hcbox supports installing the following packages:

• docker - Docker container runtime
• nodejs - Node.js runtime

Packages can be installed during server creation or on existing servers:

# During creation
hcbox up server1 --install docker

# On existing server
hcbox package install server1 docker,nodejs

You can specify versions using the package:version syntax:

# Install specific versions
hcbox package install server1 docker:24.0.5 nodejs:18

# Mix latest and specific versions
hcbox package install server1 docker nodejs:18

# Install latest versions (default)
hcbox package install server1 docker,nodejs

# List available packages
hcbox package list

# Install packages
hcbox package install server1 docker:latest nodejs:18

# Uninstall packages
hcbox package uninstall server1 docker nodejs

Note: The system automatically checks if packages are already installed and will uninstall them before reinstalling to ensure clean installations.

hcbox up server1

This will:

1. Create a new Hetzner server named server1
2. Wait for the server to be ready
3. Create a DNS A record: server1.dev.example.com
4. Install and configure Caddy for HTTPS
5. Create an SSH alias for easy access

hcbox up server1 --install docker,python

This will create a server and install the specified packages automatically.

hcbox down server1

This will:

1. Delete the server from Hetzner Cloud
2. Remove the DNS record from Cloudflare
3. Remove the SSH alias from your SSH config

hcbox package install server1 docker,python,nodejs

This will install the specified packages on an existing server.

hcbox package list

Shows all available packages that can be installed.

After creating a server, you can SSH directly using the server name:

ssh server1

Your server will be available at:

https://server1.dev.example.com

Manage Caddy web server configuration on your servers:

# Show current Caddy configuration
hcbox caddy show <server-name>

# Reset Caddy to default success page
hcbox caddy reset <server-name>

# Link Caddy to proxy to a local port
hcbox caddy link <server-name> <port>

# Link with subdomain (creates A record for subdomain)
hcbox caddy link <server-name> <port> --sub api

# Unlink main domain (resets to default page)
hcbox caddy unlink <server-name>

# Unlink specific subdomain (removes A record and resets)
hcbox caddy unlink <server-name> --sub api

• Server creation: Only creates servername.prefix.domain A record
• Subdomain linking: Creates specific A record for subdomain.servername.prefix.domain
• Reset command: Removes all subdomain A records, keeps main record, resets Caddyfile
• Unlink command: Removes specific subdomain A record and updates Caddyfile

License: MIT

This is a development tool created for personal use. This project:

• Is not affiliated with or endorsed by Hetzner Cloud GmbH
• Is not an official Hetzner CLI tool
• Is not associated with the official Hetzner Cloud API or hcloud CLI

This tool is provided as-is for educational and personal use. Use at your own risk and discretion.