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 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
- Create, pick a name, a base image and a spec. The machine is
stoppedand costs only storage. - Run, the run goes
requested → provisioning → booting → running. Billing starts when the machine is created (provisioning), so boot time is included. - 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 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.
- Creating or starting a machine needs a minimum balance, currently $1;
GET /api/v1/machines/specsreports it asbalance_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, or409 machine_lockedwhen 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: truethrows 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}/snapshotsaves 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.