Hetzner Devbox

Hetzner Devbox

Use this skill to create a long-running remote devbox for AI-agent work. It is an opinionated starting point, not a universal cloud provisioning framework.

Defaults

• Server name: agent-devbox-01
• Server type: cpx32
• Location: nbg1
• Image: ubuntu-24.04
• Admin user: admin
• Firewall name: agent-devbox-private
• Tailscale hostname: server name
• Bun version: 1.2.15

Required Local State

• hcloud, jq, ssh, ssh-add, and git must be available locally.
• HCLOUD_TOKEN and a fresh TS_AUTHKEY must be set in the environment or in .env.
• HCLOUD_SSH_KEY_NAME must be set before creating a new server.
• The Hetzner SSH private key must already be loaded into the local SSH agent. Never export, copy, paste, or write private SSH keys to disk.

The scripts load .env from the skill directory by default, or from the current working directory if no skill-local .env exists. Override with ENV_FILE=/path/to/.env.

Use scripts/check-prereqs.sh before provisioning. It checks commands, required environment values, and loaded SSH-agent identities without printing secret values.

Workflow

1. Check prerequisites:

skills/hetzner-devbox/scripts/check-prereqs.sh

1. Create or reuse the server:

skills/hetzner-devbox/scripts/create-server.sh

Set SERVER_NAME, SERVER_TYPE, LOCATION, IMAGE, or HCLOUD_SSH_KEY_NAME to override defaults. The script prints the public IPv4 address needed for the first root SSH bootstrap.

1. Run the remote hardening bootstrap:

SERVER_IPV4= skills/hetzner-devbox/scripts/bootstrap-hardening.sh

This streams the vendored scripts/bootstrap-private-vps.sh over SSH, passes TS_AUTHKEY without putting the key on the command line, and configures the server as Tailscale-only. After it finishes, verify ssh admin@ works before relying on the firewall.

1. Apply the Hetzner provider firewall:

skills/hetzner-devbox/scripts/apply-firewall.sh

The provider firewall allows only inbound ICMP and UDP 41641 for Tailscale direct WireGuard connections. It deliberately does not allow public TCP/SSH. Host UFW remains the stricter inner layer.

1. Install the devbox toolchain:

skills/hetzner-devbox/scripts/install-toolchain.sh

This installs base packages, Docker Engine plus Compose, GitHub CLI, Bun, uv, current Node LTS user-locally, Codex CLI, and Claude Code by default. Set INSTALL_* flags to 0 to opt out of optional groups. Set INSTALL_REMOTION_LIBS=1 to include headless Chromium runtime libraries.

Verification

After setup, verify from a fresh local shell:

ssh admin@agent-devbox-01 'bash -lc "id -nG; docker ps; bun --version; uv --version; node --version; gh --version | head -n 1; codex --version; claude --version"'

Also verify:

• hcloud firewall describe agent-devbox-private shows only ICMP and UDP 41641 inbound.
• sudo ufw status verbose on the server shows inbound allowed on tailscale0 and no public SSH allow rule.
• admin is in the docker group on a fresh login if Docker was installed.

Safety Rules

• Never print .env values or auth keys.
• Never materialize private SSH keys; rely on the user's local SSH agent.
• Do not delete existing Hetzner servers, firewalls, or SSH keys unless the user explicitly asks.
• If a server was created in the same run and bootstrap fails, explain the state and ask before deleting it.
• Treat adding admin to the Docker group as root-equivalent access and mention that tradeoff when relevant.
• Ask before creating paid infrastructure when running this skill from an agent session.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: getspinup
• Source: getspinup/skills
• License: MIT

Install and usage instructions live in the source repository linked above.