sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ hetzner/ setup.mdx

import PackageManagers from "../../../components/PackageManagers.astro";
export const pkgs = `alchemy@latest @alchemy.run/hetzner@latest effect @effect/platform-bun @effect/platform-node`;

Everything you need before deploying to Hetzner Cloud: the alchemy package, a Hetzner project, and an API token stored in a profile.

Prerequisites

Create a Hetzner project

Everything in Hetzner Cloud — servers, volumes, networks, tokens — lives inside a project. In the Hetzner Cloud Console:

  1. Click + New project.
  2. Give it a name (e.g. my-app) and open it.

One project per app (or per environment) is a good default: API tokens are scoped to a single project, so separate projects give you hard isolation between apps.

Generate an API token

Inside the project:

  1. Go to Security → API tokens.
  2. Click Generate API token.
  3. Give it a description (e.g. alchemy) and select Read & Write — Alchemy needs write access to create resources.
  4. Copy the token — Hetzner shows it only once.

Create a project directory

Install

Connect alchemy to Hetzner

There is no separate credentials step. The first time you run alchemy deploy (or plan, dev, destroy) on a stack that uses Hetzner.providers(), alchemy prompts for the token you generated above (and, optionally, an API endpoint override). It is saved under ~/.alchemy/credentials/<profile>/ in the selected profile and reused on subsequent commands.

In CI (CI=true) alchemy skips the prompt and reads HCLOUD_TOKEN (plus an optional HCLOUD_ENDPOINT) from the environment instead.

To re-run the setup later (e.g. to rotate the token, or configure a separate prod profile):

# Re-run the interactive setup (e.g. to rotate the token)
alchemy profile edit --reconfigure Hetzner

# Or connect Hetzner in a separate `prod` profile
alchemy profile create prod
alchemy profile edit --profile prod --add Hetzner

# Non-interactive (scripts, agents)
alchemy profile edit --add Hetzner --method stored --set token=env:HCLOUD_TOKEN

Inspect what's stored (secrets are redacted):

alchemy profile show

:::note[No SSH key setup required] Hetzner.Service deploys your code to a Server over SSH, but you don't need to create or upload an SSH key for that — alchemy generates a dedicated deploy key for each Server it creates and injects it at boot. Adding your own Hetzner.SshKey is only for your interactive ssh access. :::

State storage

Hetzner has no object-storage state backend of its own, so pick one of:

  • Alchemy.localState() — state on disk under .alchemy/ next to your code. Zero setup; right for solo projects and trying things out.
  • A cloud state store — if you also use Cloudflare or AWS, pass Cloudflare.state() or AWS.state() so state is shared with your team and CI. See State Store.

State for a Hetzner stack includes each Server's deploy SSH key (stored redacted), so for shared or production stacks prefer a remote state store over files on one laptop.

Next steps