Galon Cloud
Galon Cloud

Galon Compute

Linux virtual machines billed per minute from your prepaid balance, with SSH access.

Markdown · API reference · OpenAPI

Before you start

  • A Galon account, a project with a prepaid balance and a key with compute:read, compute:quote and compute: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:

MethodPathAuthWhat it does
GET/v1/compute/flavorskey compute:readMachine sizes and hourly prices
GET/v1/compute/imageskey compute:readAllowed images
POST/v1/compute/quoteskey compute:quoteQuote a machine (30 minutes)
POST/v1/compute/ssh-keyskey compute:writeRegister an SSH public key
POST/v1/compute/instanceskey compute:writeCreate a machine (202)
GET/v1/compute/instances/{id}key compute:readRead a machine
DELETE/v1/compute/instances/{id}key compute:deleteDelete a machine (confirm=<name>)
GET/v1/compute/usagekey compute:usageMinutes 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.

StatusCodeWhennext_action
403compute_capability_disabledCompute is not open for this account.check_project_access
503compute_price_not_configuredCompute is not open for sale yet.retry_later
409compute_quote_expiredThe quote is older than 30 minutes: request a new one.resolve_conflict
409compute_quote_mismatchThe quote was made for another size or image.resolve_conflict
402compute_budget_exceededThe balance does not cover 24 hours of running.raise_limit_or_plan
409compute_capacity_unavailableNo capacity for this size right now.resolve_conflict
422compute_ssh_key_private_refusedA private key was sent: send the .pub key.fix_request
422compute_ssh_key_weakAn RSA key under 3072 bits.fix_request
429compute_quota_exceededThe project's Compute quota is reached.raise_limit_or_plan
409compute_idempotency_conflictThis Idempotency-Key was used for a different request.resolve_conflict
422compute_delete_confirmation_requiredconfirm is not the exact machine name.fix_request
next_actionWhat to do
check_project_accessThis project or key is not allowed to do this. Its owner must review the project, its key and its account in the console.
retry_laterTemporary 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_conflictThe 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_planA 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_requestThe 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.

SizeResourcesRunning, per hourStopped, per hourRunning all month
1vcpu-1gb1 vCPU, 1 GiB memory, 10 GiB disk0.0088 USD0.00121 USD5.9136 USD
2vcpu-4gb2 vCPU, 4 GiB memory, 25 GiB disk0.023045 USD0.003025 USD15.48624 USD
4vcpu-8gb4 vCPU, 8 GiB memory, 50 GiB disk0.04609 USD0.00605 USD30.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.

More