Machines

Read MarkdownFor agents

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 isCosts
MachineA 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
RunOne start-to-stop session of a machine on dedicated compute, with its own IP address.Per minute, at the spec's price
SnapshotYour 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 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/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 subdomainPlain HTTP inside the machine
44380
84438080
20532052
20832082
20872086

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 & pathDoes
GET /machines/specsSpecs with their price per hour, minimum charge and max image size
GET /machines/imagesBase images
POST /machinesCreate, {name, base_image, spec, fallback_specs?, ephemeral_default?, snapshot_policy?, ssh_keys?} → 201
GET /machinesYour 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}/runStart, {spec?, fallback_specs?, timeout_minutes?, ephemeral?} → 202 run
POST /machines/{id}/stopStop, {force?} → 202
POST /machines/{id}/snapshotSave a running machine's changes now
POST /machines/{id}/duplicateCopy, {name} → 201
GET /machines/{id}/runsRuns, newest first
GET /runs/{id}One run, state, IP, subdomain, spec, timings, cost, snapshot state, stop reason
GET /runs/{id}/eventsThe run's timeline
GET /runs/{id}/statsCPU, memory, disk and network, in 10-minute samples
POST /runs/{id}/sessionA short-lived console session
GET /machines/{id}/schedules, POST /machines/{id}/schedulesList 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

HTTPcodeWhen
400bad_requestAn invalid field, unknown spec or base image, bad SSH key, a cron that fires more often than every 15 minutes. The message says which
400image_too_large_for_specThe saved image doesn't fit the spec's max image size
402insufficient_creditYour balance is below the minimum, or can't cover the start hold
402machines_daily_cap_reachedYour account reached today's machines spend limit
403service_not_allowed_for_keyThis key's service list doesn't include Machines
404not_foundNo such machine, run or schedule on your account
409machine_runningThe machine is running or still finishing a stop
409machine_lockedThe machine is running somewhere else
409machine_not_runningStop, snapshot or console on a machine that isn't running
429machine_cap_reachedYour running-machines limit, or the platform's capacity, is full
429rate_limitedToo many requests, retry-after header
503machines_disabledMachines are switched off
503provider_unavailableMachines are temporarily unavailable, try again shortly
503subdomain_pool_exhaustedNo 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.