@apiclient.xyz/hetznercloud

@apiclient.xyz/hetznercloud is an unofficial TypeScript client for the Hetzner Cloud API. It wraps the day-to-day infrastructure primitives this package currently supports - servers, volumes, and firewalls - behind small classes that keep the original Hetzner resource data available while giving you convenient methods for create, list, label-filter, and delete workflows.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Why Use It?

• TypeScript-first ESM package for Hetzner Cloud automation.
• Simple HetznerAccount object that owns API token authentication.
• Resource classes for HetznerServer, HetznerVolume, and HetznerFirewall.
• Label-based lookup helpers for predictable automation runs.
• Typed request and response shapes generated from the Hetzner OpenAPI specification.
• Escape hatch via account.request() whenever you need an endpoint that does not yet have a higher-level class method.

Install

pnpm add @apiclient.xyz/hetznercloud

Quick Start

import {
  HetznerAccount,
  HetznerFirewall,
  HetznerVolume,
} from '@apiclient.xyz/hetznercloud';

const account = new HetznerAccount('your-hetzner-api-token');

const server = await account.createServer({
  name: 'demo-api-01',
  type: 'cpx31',
  location: 'nbg1',
  labels: {
    app: 'demo-api',
    environment: 'staging',
  },
  userData: '#!/bin/bash\napt-get update',
});

const volume = await HetznerVolume.create(account, {
  name: 'demo-api-data',
  size: 25,
  location: 'nbg1',
  labels: {
    app: 'demo-api',
    environment: 'staging',
  },
  server,
});

const firewall = await HetznerFirewall.create(account, {
  name: 'demo-api-web',
  labels: {
    app: 'demo-api',
    environment: 'staging',
  },
  rules: [
    {
      direction: 'in',
      protocol: 'tcp',
      port: '443',
      source_ips: ['0.0.0.0/0', '::/0'],
    },
  ],
});

console.log(server.data);
console.log(volume.data);
console.log(firewall.data);

Core Concepts

Accounts

HetznerAccount stores your Hetzner Cloud API token and exposes the shared request layer used by all resource classes.

import { HetznerAccount } from '@apiclient.xyz/hetznercloud';

const account = new HetznerAccount('your-hetzner-api-token');

Available account helpers:

• account.getServers() lists all servers visible to the token.
• account.getServersByLabel(labels) lists servers and returns exact label matches.
• account.createServer(options) creates a new server.
• account.request(method, path, payload) calls the Hetzner Cloud API directly.

The direct request helper returns an object shaped like this:

const response = await account.request('GET', '/servers', {});

console.log(response.statusCode);
console.log(response.body);

The current implementation logs request metadata and response bodies to the console, which is useful during automation debugging and important to remember when running with sensitive payloads.

Servers

Servers are represented by HetznerServer. The package can create, list, filter, and delete them.

const server = await account.createServer({
  name: 'worker-01',
  type: 'cpx41',
  location: 'fsn1',
  labels: {
    role: 'worker',
  },
  userData: '#!/bin/bash\necho ready',
});

const allServers = await account.getServers();
const workerServers = await account.getServersByLabel({ role: 'worker' });

await server.delete();

createServer() currently creates Ubuntu 22.04 servers, starts them immediately, and enables public IPv4 and IPv6 networking.

Supported server type names are:

cx11, cx21, cx31, cx41, cx51,
ccx11, ccx21, ccx31, ccx41, ccx51,
ccx13, ccx23, ccx33, ccx43, ccx53, ccx63,
cpx11, cpx21, cpx31, cpx41, cpx51, cpx61, cpx70, cpx71, cpx90

Supported location names are:

fsn1, nbg1, hel1, ash, hil

Volumes

Volumes are represented by HetznerVolume. A volume is created for and attached to an existing HetznerServer instance.

import { HetznerVolume } from '@apiclient.xyz/hetznercloud';

const volume = await HetznerVolume.create(account, {
  name: 'worker-01-data',
  size: 50,
  location: 'fsn1',
  labels: {
    role: 'worker',
  },
  server,
});

const allVolumes = await HetznerVolume.getVolumes(account);
const workerVolumes = await HetznerVolume.getVolumesByLabel(account, { role: 'worker' });

await volume.delete();

HetznerVolume.create() currently formats new volumes as xfs and attaches them to options.server.data.id.

Firewalls

Firewalls are represented by HetznerFirewall. The package can create firewalls with rules, list them, filter them by label, and delete them.

import { HetznerFirewall } from '@apiclient.xyz/hetznercloud';

const firewall = await HetznerFirewall.create(account, {
  name: 'web-ingress',
  labels: {
    app: 'frontend',
  },
  rules: [
    {
      direction: 'in',
      protocol: 'tcp',
      port: '80',
      source_ips: ['0.0.0.0/0', '::/0'],
    },
    {
      direction: 'in',
      protocol: 'tcp',
      port: '443',
      source_ips: ['0.0.0.0/0', '::/0'],
    },
  ],
});

const allFirewalls = await HetznerFirewall.getFirewalls(account);
const frontendFirewalls = await HetznerFirewall.getFirewallsByLabel(account, { app: 'frontend' });

await firewall.delete();

Label Filtering

The label helpers perform exact matches for every key/value pair you pass in. This makes them practical for idempotent automation where labels are your resource ownership contract.

const servers = await account.getServersByLabel({
  app: 'demo-api',
  environment: 'staging',
});

Direct API Access

Use account.request() when you need access to an endpoint that is not wrapped yet. Pass the HTTP method, the API path below /v1, and a payload object.

const locationsResponse = await account.request('GET', '/locations', {});

if (locationsResponse.statusCode >= 200 && locationsResponse.statusCode < 300) {
  console.log(locationsResponse.body);
}

For non-GET and non-DELETE requests, the payload is sent as JSON.

Development

pnpm install
pnpm test
pnpm run build

Tests use @git.zone/tstest. Live Hetzner API tests look for HETZNER_API_TOKEN; without a usable token, the live API parts are skipped.

The OpenAPI types can be refreshed with:

pnpm run updateOpenapi

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.