# Machines

> Your own Linux machines, with root, systemd, Docker and SSH inside. A machine costs only storage while it's stopped; start it when you need it, and it bills per minute until you stop it. Every machine gets a fixed subdomain with HTTPS handled for you. Manage machines in the [dashboard](/dashboard#/machines) or through the API below.

## Concepts

|  | What it is | Costs |
| --- | --- | --- |
| **Machine** | A saved Linux image, a base image plus your changes, with a fixed subdomain. It isn't running by default. | Storage of your changes, per GB-day |
| **Run** | One start-to-stop session of a machine on dedicated compute, with its own IP address. | Per minute, at the spec's price |
| **Snapshot** | Your changes, saved when a run stops. Only the latest snapshot is kept; the next run starts from it. | Included in storage |

Base images: `ubuntu-24.04` (systemd, sshd and Docker inside), `python`, `node`, `desktop` (an XFCE desktop in your browser) and `browser` (headful Chromium for agents, viewable in your browser). `GET /api/v1/machines/images` lists them.

## Lifecycle

1. **Create**, pick a name, a base image and a spec. The machine is `stopped` and costs only storage.
2. **Run**, the run goes `requested → provisioning → booting → running`. Billing starts when the machine is created (`provisioning`), so boot time is included.
3. **Stop**, `stopping → snapshotting → stopped`: your changes are saved, then the machine shuts down. Billing ends the moment you ask it to stop; saving happens on our time.

A run that can't be provisioned ends `failed`. A provider failure before the machine is ready isn't billed.

## Pricing

- **Compute**, per minute at the spec's hourly price, from the moment the machine is created until you request the stop, with a **minimum charge per run**. Prices per spec are on the [pricing page](/pricing#price-compute) and in `GET /api/v1/machines/specs`.
- **The minimum charge**, a provider failure before the machine is ready isn't billed at all. Any other stop, yours, a timeout, a schedule, the balance running out, bills at least the spec's minimum charge.
- **Image storage**, per GB-day, for **your changes only**. Base images are free.
- **Transfer**, per GB of your image moving in and out of storage when runs start and stop.
- Billed from your **credit** only, never from a plan, and counted toward your [monthly spend cap](/docs/quotas).
- Creating or starting a machine needs a minimum balance, currently **$1**; `GET /api/v1/machines/specs` reports it as `balance_floor_usd`. Starting holds about an hour of the spec (at least that minimum) of your balance while the run lasts.
- Compute never takes your balance below zero: when credit runs out, the run is stopped (stop reason `balance`). Image storage keeps accruing and can take the balance below zero.

## Rules

- **Caps**, up to **3 machines running at once** per account by default. When that, or the platform's capacity, is full, a run is refused with `429 machine_cap_reached`, nothing is queued.
- **One place at a time**, a machine runs in exactly one place. Starting it again while it runs is refused (`409 machine_running`, or `409 machine_locked` when it runs elsewhere). To work on two copies, duplicate it.
- **Duplicate**, a full, independent copy with its own subdomain. Its image is billed separately, even while the two are identical.
- **Ephemeral runs**, a run with `ephemeral: true` throws its changes away on stop; the machine keeps its previous image. A machine can default to ephemeral runs.
- **Image size**, your saved image must fit the spec's max image size, or the run is refused with `400 image_too_large_for_spec`.
- **Fallback specs**, if the requested spec can't be provisioned, the fallbacks are tried in order; you're billed at the spec actually used.
- **Delete**, only when no run is live or still finishing its stop.

## Subdomains and ports

Every machine has a fixed subdomain, such as `k3v9q2m7x4w8c1z5n6b0.194531.xyz`. It points at the machine while it runs. **Serve plain HTTP inside. TLS is handled for you**: HTTPS on the subdomain is decrypted before it reaches the machine and forwarded as plain HTTP to the matching port inside.

| HTTPS on the subdomain | Plain HTTP inside the machine |
| --- | --- |
| `443` | `80` |
| `8443` | `8080` |
| `2053` | `2052` |
| `2083` | `2082` |
| `2087` | `2086` |

Plain HTTP passes straight through on `80`, `8080`, `8880`, `2052`, `2082`, `2086` and `2095`. Only these ports work on the subdomain, that's the edge proxy's rule for proxied ports. Any other port is reachable on the run's IP address, which changes every run.

## SSH

Add your OpenSSH public keys to the machine; they're installed for `root` on port **22** inside the machine: `ssh root@<run IP>`. Port `2222` is KhaBot's own and isn't reachable; port `2096` serves the machine's console.

## Console and desktop

While a machine runs, the dashboard opens a **web terminal** on it, and, for the `desktop` and `browser` images, the **desktop or browser view**. Each opening uses a short-lived session from `POST /api/v1/runs/{id}/session`:

```
{ "token": "eyJ…", "agent_base": "https://k3v9q2m7x4w8c1z5n6b0.194531.xyz:2096", "expires_in": 900 }
```

Open `{agent_base}/console#token={token}`, or `/vnc` for the desktop or browser view. The token goes in the URL **fragment**, never the query string, so it isn't sent to any server log; the page exchanges it itself. The session lasts 15 minutes and works only for that run.

## Schedules

- Start a machine on a cron timetable, `minute hour day month weekday`, in **UTC**.
- A schedule fires at most every **15 minutes**.
- Each schedule sets a timeout (the run stops gracefully when it's up), whether runs are ephemeral, and, when it's created, the spec and fallbacks.
- If the machine is already running when a schedule fires, that run is skipped; a missed run isn't made up later.

## Stopping and snapshots

- A normal stop saves your changes, then shuts the machine down. Billing ends at the stop request.
- **Aborting a stop is not possible**, once requested, the machine stops.
- A **force stop** (`force: true`) destroys the machine immediately, **without saving**: every change since the last snapshot is lost.
- Optionally, a running machine also saves its changes periodically while it's idle.
- `POST /machines/{id}/snapshot` saves the changes of a running machine now.
- If a machine stops responding for 20 minutes, it's stopped (stop reason `heartbeat`) after an attempt to save it.

## API

Base URL `https://khabot.com/api/v1`. Authenticate with your KhaBot key, a key with a restricted service list needs **Machines** among its services.

| Method & path | Does |
| --- | --- |
| `GET /machines/specs` | Specs with their price per hour, minimum charge and max image size |
| `GET /machines/images` | Base images |
| `POST /machines` | Create, `{name, base_image, spec, fallback_specs?, ephemeral_default?, snapshot_policy?, ssh_keys?}` → `201` |
| `GET /machines` | Your machines |
| `GET /machines/{id}` | One machine, subdomain, status, current run, image size, cost this month |
| `PATCH /machines/{id}` | Change name, spec (only while stopped), fallbacks, SSH keys, snapshot policy, ephemeral default |
| `DELETE /machines/{id}` | Delete the machine and its image |
| `POST /machines/{id}/run` | Start, `{spec?, fallback_specs?, timeout_minutes?, ephemeral?}` → `202` run |
| `POST /machines/{id}/stop` | Stop, `{force?}` → `202` |
| `POST /machines/{id}/snapshot` | Save a running machine's changes now |
| `POST /machines/{id}/duplicate` | Copy, `{name}` → `201` |
| `GET /machines/{id}/runs` | Runs, newest first |
| `GET /runs/{id}` | One run, state, IP, subdomain, spec, timings, cost, snapshot state, stop reason |
| `GET /runs/{id}/events` | The run's timeline |
| `GET /runs/{id}/stats` | CPU, memory, disk and network, in 10-minute samples |
| `POST /runs/{id}/session` | A short-lived console session |
| `GET /machines/{id}/schedules`, `POST /machines/{id}/schedules` | List and create schedules |
| `PATCH /schedules/{id}`, `DELETE /schedules/{id}` | Change (cron, timeout, ephemeral, enabled) and delete |

```
# create
curl https://khabot.com/api/v1/machines \
  -H "Authorization: Bearer kb_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name": "build-box", "base_image": "ubuntu-24.04", "spec": "basic-1-2",
       "ssh_keys": ["ssh-ed25519 AAAA… you@laptop"]}'

# start it, stopping on its own after an hour
curl -X POST https://khabot.com/api/v1/machines/m_abc123def456/run \
  -H "Authorization: Bearer kb_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"timeout_minutes": 60}'

# stop it (changes are saved)
curl -X POST https://khabot.com/api/v1/machines/m_abc123def456/stop \
  -H "Authorization: Bearer kb_YOUR_KEY" -H "Content-Type: application/json" -d '{}'

# run it every weekday at 09:00 UTC for 30 minutes
curl https://khabot.com/api/v1/machines/m_abc123def456/schedules \
  -H "Authorization: Bearer kb_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"cron": "0 9 * * 1-5", "timeout_minutes": 30}'
```

## Errors

| HTTP | code | When |
| --- | --- | --- |
| 400 | `bad_request` | An invalid field, unknown spec or base image, bad SSH key, a cron that fires more often than every 15 minutes. The `message` says which |
| 400 | `image_too_large_for_spec` | The saved image doesn't fit the spec's max image size |
| 402 | `insufficient_credit` | Your balance is below the minimum, or can't cover the start hold |
| 402 | `machines_daily_cap_reached` | Your account reached today's machines spend limit |
| 403 | `service_not_allowed_for_key` | This key's service list doesn't include Machines |
| 404 | `not_found` | No such machine, run or schedule on your account |
| 409 | `machine_running` | The machine is running or still finishing a stop |
| 409 | `machine_locked` | The machine is running somewhere else |
| 409 | `machine_not_running` | Stop, snapshot or console on a machine that isn't running |
| 429 | `machine_cap_reached` | Your running-machines limit, or the platform's capacity, is full |
| 429 | `rate_limited` | Too many requests, `retry-after` header |
| 503 | `machines_disabled` | Machines are switched off |
| 503 | `provider_unavailable` | Machines are temporarily unavailable, try again shortly |
| 503 | `subdomain_pool_exhausted` | No subdomain is free for a new machine right now |

## Not available yet

- GPUs, machines are CPU only.
- Fixed IP addresses, a machine's IP changes every run; use its subdomain.
- Running a machine on your own computer.
- Extra volumes or attached disks.
