The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 110 lines 3.53 KB
Raw
1 ---
2 title: Setup
3 description: Install Alchemy and connect it to Hetzner Cloud — create a project, generate an API token, and store it in a profile.
4 ---
5
6 import PackageManagers from "../../../components/PackageManagers.astro";
7
8 export const pkgs = `alchemy@latest @alchemy.run/hetzner@latest effect @effect/platform-bun @effect/platform-node`;
9
10 Everything you need before deploying to Hetzner Cloud: the alchemy
11 package, a Hetzner project, and an API token stored in a profile.
12
13 ## Prerequisites
14
15 - [Bun](https://bun.sh) or Node.js 22+
16 - A [Hetzner Cloud](https://console.hetzner.com) account
17
18 ## Create a Hetzner project
19
20 Everything in Hetzner Cloud — servers, volumes, networks, tokens —
21 lives inside a **project**. In the
22 [Hetzner Cloud Console](https://console.hetzner.com):
23
24 1. Click **+ New project**.
25 2. Give it a name (e.g. `my-app`) and open it.
26
27 One project per app (or per environment) is a good default: API
28 tokens are scoped to a single project, so separate projects give you
29 hard isolation between apps.
30
31 ## Generate an API token
32
33 Inside the project:
34
35 1. Go to **Security** → **API tokens**.
36 2. Click **Generate API token**.
37 3. Give it a description (e.g. `alchemy`) and select
38 **Read & Write** — Alchemy needs write access to create resources.
39 4. Copy the token — Hetzner shows it **only once**.
40
41 ## Create a project directory
42
43 <PackageManagers init dir="my-app" />
44
45 ## Install
46
47 <PackageManagers add={pkgs} />
48
49 ## Connect alchemy to Hetzner
50
51 There is no separate credentials step. The first time you run
52 `alchemy deploy` (or `plan`, `dev`, `destroy`) on a stack that uses
53 `Hetzner.providers()`, alchemy prompts for the token you generated
54 above (and, optionally, an API endpoint override). It is saved under
55 `~/.alchemy/credentials/<profile>/` in the selected
56 [profile](/environments/profiles) and reused on subsequent commands.
57
58 In CI (`CI=true`) alchemy skips the prompt and reads `HCLOUD_TOKEN`
59 (plus an optional `HCLOUD_ENDPOINT`) from the environment instead.
60
61 To re-run the setup later (e.g. to rotate the token, or configure a
62 separate `prod` profile):
63
64 ```sh
65 # Re-run the interactive setup (e.g. to rotate the token)
66 alchemy profile edit --reconfigure Hetzner
67
68 # Or connect Hetzner in a separate `prod` profile
69 alchemy profile create prod
70 alchemy profile edit --profile prod --add Hetzner
71
72 # Non-interactive (scripts, agents)
73 alchemy profile edit --add Hetzner --method stored --set token=env:HCLOUD_TOKEN
74 ```
75
76 Inspect what's stored (secrets are redacted):
77
78 ```sh
79 alchemy profile show
80 ```
81
82 :::note[No SSH key setup required]
83 `Hetzner.Service` deploys your code to a Server over SSH, but you
84 don't need to create or upload an SSH key for that — alchemy
85 generates a dedicated deploy key for each Server it creates and
86 injects it at boot. Adding your own `Hetzner.SshKey` is only for
87 *your* interactive `ssh` access.
88 :::
89
90 ## State storage
91
92 Hetzner has no object-storage state backend of its own, so pick one
93 of:
94
95 - **`Alchemy.localState()`** — state on disk under `.alchemy/` next
96 to your code. Zero setup; right for solo projects and trying
97 things out.
98 - **A cloud state store** — if you also use Cloudflare or AWS, pass
99 `Cloudflare.state()` or `AWS.state()` so state is shared with
100 your team and CI. See [State Store](/state-store).
101
102 State for a Hetzner stack includes each Server's deploy SSH key
103 (stored redacted), so for shared or production stacks prefer a
104 remote state store over files on one laptop.
105
106 ## Next steps
107
108 - [Tutorial part 1](/hetzner/tutorial/part-1) — deploy your first
109 Server.
110 - [Hetzner overview](/hetzner) — the map of resources and guides.