Skip to content

Install & run locally

You can run cloudalone on your laptop against the stub backend: no virtualization, no Linux host, no root. It's the fastest way to see the API work and to develop against it. Booting real VMs needs a Linux box; that's covered in Deploying to a host.

Requirements

Works on macOS or Linux with the stub backend.

Install

git clone <this-repo> cloudalone && cd cloudalone
uv sync

Run against the stub backend

CLOUDALONE_BACKEND=stub CLOUDALONE_TOKEN=dev-token uv run cloudalone serve

The stub backend accepts every request and tracks state in SQLite, but does no real virtualization; perfect for exploring the API.

Loopback-only dev server

serve refuses to start with the default token unless you pass --dev, which forces a loopback bind. For anything reachable, set a real CLOUDALONE_TOKEN (see Configuration).

Talk to it

export HCLOUD_TOKEN=dev-token
export HCLOUD_ENDPOINT=http://localhost:8000/v1
hcloud server-type list
hcloud server create --name t1 --type small --image debian-13
hcloud server list

curl -s -H "Authorization: Bearer dev-token" \
  http://localhost:8000/v1/server_types | python3 -m json.tool

from hcloud import Client
c = Client(token="dev-token", api_endpoint="http://localhost:8000/v1")
print([t.name for t in c.server_types.get_all()])

The repo ships a conformance script that round-trips the real hcloud client against the stub (create → poll → list → power → delete):

uv run python scripts/conformance.py     # prints "CONFORMANCE OK"

Next