Before you start
- A Galon account, a project with a prepaid balance and a key with
compute:read,compute:quoteandcompute:write. - An SSH key pair on your machine: you register the PUBLIC key (
.pub) only.
Quickstart
Every example reads GALON_API_BASE (https://api.galon.ai/v1) and GALON_API_KEY from the environment and prints the HTTP status and the JSON body.
1. Set your key. Export the base URL and your key.
curl
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..."2. List the machine sizes. Each size gives its vCPU, memory, disk and hourly price, running and stopped.
curl
curl -sS -X GET "$GALON_API_BASE/compute/flavors" \
-H "Authorization: Bearer $GALON_API_KEY" \
-w '\n%{http_code}\n'Python 3 (standard library)
import json, os, urllib.error, urllib.request
req = urllib.request.Request(
os.environ["GALON_API_BASE"] + "/compute/flavors",
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
method="GET",
)
try:
with urllib.request.urlopen(req) as res:
print(res.status, json.load(res))
except urllib.error.HTTPError as err: # the error body carries detail.code and detail.next_action
print(err.code, json.load(err))
Node.js 18+ (fetch)
const res = await fetch(`${process.env.GALON_API_BASE}/compute/flavors`, {
method: "GET",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_compute_flavors", "arguments": {}}}' \
-w '\n%{http_code}\n'3. List the images. The operating systems a machine can run, with their fingerprint.
curl
curl -sS -X GET "$GALON_API_BASE/compute/images" \
-H "Authorization: Bearer $GALON_API_KEY" \
-w '\n%{http_code}\n'Python 3 (standard library)
import json, os, urllib.error, urllib.request
req = urllib.request.Request(
os.environ["GALON_API_BASE"] + "/compute/images",
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
method="GET",
)
try:
with urllib.request.urlopen(req) as res:
print(res.status, json.load(res))
except urllib.error.HTTPError as err: # the error body carries detail.code and detail.next_action
print(err.code, json.load(err))
Node.js 18+ (fetch)
const res = await fetch(`${process.env.GALON_API_BASE}/compute/images`, {
method: "GET",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "list_compute_images", "arguments": {}}}' \
-w '\n%{http_code}\n'4. Get a quote. A quote fixes the price of one size and image for 30 minutes. Create the machine with its id.
curl
curl -sS -X POST "$GALON_API_BASE/compute/quotes" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"flavor": "1vcpu-1gb", "image": "ubuntu-24.04"}' \
-w '\n%{http_code}\n'Python 3 (standard library)
import json, os, urllib.error, urllib.request
req = urllib.request.Request(
os.environ["GALON_API_BASE"] + "/compute/quotes",
data=json.dumps({"flavor": "1vcpu-1gb", "image": "ubuntu-24.04"}).encode(),
headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
"Content-Type": "application/json"},
method="POST",
)
try:
with urllib.request.urlopen(req) as res:
print(res.status, json.load(res))
except urllib.error.HTTPError as err: # the error body carries detail.code and detail.next_action
print(err.code, json.load(err))
Node.js 18+ (fetch)
const res = await fetch(`${process.env.GALON_API_BASE}/compute/quotes`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({flavor: "1vcpu-1gb", image: "ubuntu-24.04"}),
});
console.log(res.status, JSON.stringify(await res.json()));
MCP (JSON-RPC over HTTP)
curl -sS -X POST "$GALON_API_BASE/mcp" \
-H "Authorization: Bearer $GALON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "quote_compute_instance", "arguments": {"flavor": "1vcpu-1gb", "image": "ubuntu-24.04"}}}' \
-w '\n%{http_code}\n'Concepts
Quote, then create. POST /v1/compute/quotes prices a size and an image; POST /v1/compute/instances with that quote_id, your ssh_key_ids and an Idempotency-Key answers 202: the machine is created in the background (GET /v1/compute/instances/{id}).
Budget first. A machine is created only if the prepaid balance covers 24 hours of running (402 compute_budget_exceeded).
Delete with its name. DELETE /v1/compute/instances/{id}?confirm=<name> deletes a machine only with its exact name (compute_delete_confirmation_required).
Public keys only. A private key is refused (compute_ssh_key_private_refused); RSA keys need 3072 bits or more, ed25519 is recommended.
API reference
These routes are served by the code but are not in the OpenAPI contract yet:
| Method | Path | Auth | What it does |
|---|---|---|---|
| GET | /v1/compute/flavors | key compute:read | Machine sizes and hourly prices |
| GET | /v1/compute/images | key compute:read | Allowed images |
| POST | /v1/compute/quotes | key compute:quote | Quote a machine (30 minutes) |
| POST | /v1/compute/ssh-keys | key compute:write | Register an SSH public key |
| POST | /v1/compute/instances | key compute:write | Create a machine (202) |
| GET | /v1/compute/instances/{id} | key compute:read | Read a machine |
| DELETE | /v1/compute/instances/{id} | key compute:delete | Delete a machine (confirm=<name>) |
| GET | /v1/compute/usage | key compute:usage | Minutes and amounts of the month |
Errors
Every error is JSON: {"detail": {"code", "message", "next_action"}}. next_action.code is stable, next_action.hint says what to do next, and console_url is added when a person must act. The codes below are those this service returns.
| Status | Code | When | next_action |
|---|---|---|---|
| 403 | compute_capability_disabled | Compute is not open for this account. | check_project_access |
| 503 | compute_price_not_configured | Compute is not open for sale yet. | retry_later |
| 409 | compute_quote_expired | The quote is older than 30 minutes: request a new one. | resolve_conflict |
| 409 | compute_quote_mismatch | The quote was made for another size or image. | resolve_conflict |
| 402 | compute_budget_exceeded | The balance does not cover 24 hours of running. | raise_limit_or_plan |
| 409 | compute_capacity_unavailable | No capacity for this size right now. | resolve_conflict |
| 422 | compute_ssh_key_private_refused | A private key was sent: send the .pub key. | fix_request |
| 422 | compute_ssh_key_weak | An RSA key under 3072 bits. | fix_request |
| 429 | compute_quota_exceeded | The project's Compute quota is reached. | raise_limit_or_plan |
| 409 | compute_idempotency_conflict | This Idempotency-Key was used for a different request. | resolve_conflict |
| 422 | compute_delete_confirmation_required | confirm is not the exact machine name. | fix_request |
| next_action | What to do |
|---|---|
check_project_access | This project or key is not allowed to do this. Its owner must review the project, its key and its account in the console. |
retry_later | Temporary error on Galon's side. Retry with exponential backoff and the same Idempotency-Key; if it lasts, contact support with the X-Request-Id header. |
resolve_conflict | The request conflicts with the resource state or with an earlier request under the same Idempotency-Key. Read the resource first; for a new intent, use a new Idempotency-Key. |
raise_limit_or_plan | A plan quota or a spending limit is reached. Raise the limit or change the plan in the console, or wait for the next period, then retry. |
fix_request | The request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged. |
Limits, free tier and pricing
Billed per minute from the prepaid balance, in US dollars, read from the platform each time this page is served. A stopped machine pays for its disk only. The monthly figure assumes it runs all month.
| Size | Resources | Running, per hour | Stopped, per hour | Running all month |
|---|---|---|---|---|
1vcpu-1gb | 1 vCPU, 1 GiB memory, 10 GiB disk | 0.0088 USD | 0.00121 USD | 5.9136 USD |
2vcpu-4gb | 2 vCPU, 4 GiB memory, 25 GiB disk | 0.023045 USD | 0.003025 USD | 15.48624 USD |
4vcpu-8gb | 4 vCPU, 8 GiB memory, 50 GiB disk | 0.04609 USD | 0.00605 USD | 30.97248 USD |
Outbound traffic: 0.0099 USD per GiB.
FAQ
How am I billed?
Per minute, from the prepaid balance: the running price while the machine runs, the stopped price (disk) while it is stopped, nothing once it is deleted.
Can my agent create a machine?
Yes, with a key that has compute:write, after a quote, within the balance.