# Galon Compute

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

## 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**

```bash
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**

```bash
curl -sS -X GET "$GALON_API_BASE/compute/flavors" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
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)**

```js
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)**

```bash
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**

```bash
curl -sS -X GET "$GALON_API_BASE/compute/images" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
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)**

```js
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)**

```bash
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**

```bash
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)**

```python
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)**

```js
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)**

```bash
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.

## More

- [Authentication](/cloud/docs/platform/authentication)
- [Projects: live and test](/cloud/docs/platform/environments)
- [Prepaid balance](/cloud/docs/platform/balance)
- [Quotas and rate limits](/cloud/docs/platform/quotas)
- [Terms of Service](/legal/terms-of-service)
- [Acceptable Use Policy](/legal/acceptable-use-policy)
- [Privacy Policy](/legal/privacy-policy)
- [Refunds and prepaid balance](/legal/prepaid-balance-and-refund-policy)
- [Legal Notice](/legal/legal-notice)
- [All legal documents](/legal)
