Hetzner Cloud API Mock
Stateful mock server for the Hetzner Cloud API, built with FastAPI and SQLite. Use it to test integrations without real cloud resources — especially with the official hcloud-python SDK.
Quick start
pip install -e ".[dev]"
HCLOUD_MOCK_TOKENS=test-token uvicorn hcloud_mock.main:app --host 0.0.0.0 --port 8080
```
Usage with hcloud-python
from hcloud import Client
client = Client(token="test-token", api_endpoint="http://127.0.0.1:8080/v1")
response = client.servers.create(
name="my-server",
server_type="cpx22",
image="ubuntu-24.04",
location="fsn1",
)
print(response.action.status) # running
print(response.server.status) # initializing
response.action.wait_until_finished()
for action in response.next_actions:
action.wait_until_finished()
print(client.servers.get_by_id(response.server.id).status) # running
```
By default actions are asynchronous: the API returns status: running immediately and completes the work in the background (like the real Hetzner API). Use action.wait_until_finished() from hcloud-python, or poll GET /actions/{id}.
| Variable | Default | Description |
|----------|---------|-------------|
| HCLOUD_MOCK_ASYNC_ACTIONS | true | Return actions as running and complete them in a background worker |
| HCLOUD_MOCK_ACTION_DELAY_MS | 1000 | Simulated duration before an action reaches success |
Usage with curl
curl -H "Authorization: Bearer test-token" http://127.0.0.1:8080/v1/locations
curl -H "Authorization: Bearer test-token" http://127.0.0.1:8080/v1/servers
Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| HCLOUD_MOCK_DB_PATH | ./hcloud-mock.db | SQLite database path |
| HCLOUD_MOCK_TOKENS | test-token | Comma-separated valid API tokens |
| HCLOUD_MOCK_ASYNC_ACTIONS | true | Async action pipeline (running → success) |
| HCLOUD_MOCK_ACTION_DELAY_MS | 1000 | Simulated action duration in milliseconds |
| HCLOUD_MOCK_RATE_LIMIT | 3600 | Rate limit header value |
| HCLOUD_MOCK_HOST | 0.0.0.0 | Server bind host |
| HCLOUD_MOCK_PORT | 8080 | Server bind port |
Reset state (testing)
curl -X POST -H "Authorization: Bearer test-token" http://127.0.0.1:8080/v1/__mock/reset
[... continued on GitHub]