Change resources through the Hetzner API
hetzner_executeExecute validated JavaScript to create, update, or delete Hetzner Cloud and Robot resources; billed and destructive requests require explicit approval before sending.
Instructions
Run JavaScript that changes Hetzner resources (POST, PUT, DELETE as well as GET). Changes are real and immediate: they can create billable resources, cause downtime or delete data permanently. Through robot this includes ordering and cancelling dedicated servers, hardware resets, and firewall rules that can lock everyone out of a server (POST /firewall/{server-number} replaces the whole rule set: read it first and send all rules back, except output rules named "Block mail ports", which Hetzner prepends itself and would duplicate; the update is asynchronous, poll until status is no longer "in process"). Look the operation up with hetzner_search first, use hetzner_query for pure reads, and act only on resources the user named.
Guard: requests that cost money (creating servers, volumes, load balancers, IPs, snapshots, Storage Boxes, type changes, backups, Robot orders) are refused unless the operator switched billed requests on. Billed requests and destructive ones (every DELETE, rebuilding a server, disabling backups, importing a zone file, Robot cancellations and OS installations) are not sent on the first attempt: the result states what they do and the price. Report that to the user and wait for their answer.
Globals available in the code:
hetzner.request({ method = 'GET', path, query?, body?, api? }) -> parsed JSON body (null if empty)
hetzner.get(path, query?) / hetzner.post(path, body?) / hetzner.put(path, body?) / hetzner.delete(path)
hetzner.paginate(path, query?, { maxPages = 50 }?) -> all items of a list endpoint across pages
hetzner.waitForAction(actionOrResponse, { timeoutMs = 90000 }?) -> finished action, throws if it failed
sleep(ms), console.log(...)
robot.get(path, query?) / robot.post(path, body?) / robot.put(path, body?) / robot.delete(path) / robot.request({...})
Paths are relative to the API root, e.g. "/servers/123" (no host, no /v1). Storage Box paths are routed
to api.hetzner.com automatically. Array query values become repeated keys. Failed calls throw an Error
with .status, .code and .details. No fetch, require or other network access exists.
Every request is checked against the API reference before it is sent (operation exists, known query and
body fields, required fields, types, enum values); a mismatch throws with code "validation_failed" and
nothing is sent. Only if the reference itself is wrong: hetzner.request({ ..., validate: false }).
hetzner is the Cloud API of the selected project. robot is the Robot webservice for dedicated servers
(NOT available: no Robot webservice user is configured); it is account-wide and ignores project. Robot paths
are singular ("/server", "/firewall/{server-number}"), have no pagination and no actions, and are rate
limited per endpoint (see "Request limit" in describe()). Pass Robot bodies as plain objects; they are
sent form-encoded, nested values become rules[input][0][action]=accept.
Most Cloud changes return an "action" that runs asynchronously; await hetzner.waitForAction(response) before relying on the result.
Examples: async () => { const res = await hetzner.post('/servers/123/actions/reboot'); return await hetzner.waitForAction(res); } async () => { const res = await hetzner.post('/servers', { name: 'web-1', server_type: 'cx23', image: 'ubuntu-24.04', location: 'nbg1', ssh_keys: ['my-key'] }); await hetzner.waitForAction(res); return { id: res.server.id, ip: res.server.public_net.ipv4.ip }; }
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"code": "<code>"
},
"name": "hetzner_execute"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JavaScript: an async arrow function whose return value is the result. Return only the fields you need. | |
| project | No | Hetzner Cloud project to use. Only needed when several projects are available. | |
| confirmed | No | Set true only after the user approved the billed or destructive requests of exactly this code. Without it such requests are not sent; the result says what they would do and cost. |