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
- Bun or Node.js 22+
- A Hetzner Cloud account
Create a Hetzner project
Everything in Hetzner Cloud — servers, volumes, networks, tokens — lives inside a project. In the Hetzner Cloud Console:
- Click + New project.
- 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:
- Go to Security → API tokens.
- Click Generate API token.
- Give it a description (e.g.
alchemy) and select Read & Write — Alchemy needs write access to create resources. - 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()orAWS.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
- Tutorial part 1 — deploy your first Server.
- Hetzner overview — the map of resources and guides.