Machines

#

A server for a few hours, started from your code and paid for by Barua. Ask for one with a size, where it runs, your SSH public key and when it ends, and it answers at once with its address; sign in as root with your key once it shows as running, usually within a minute. Machines is switched on by Barua for the accounts and communities it supports.

Every machine has its end before it exists: expiresInMinutes is required, and Barua destroys the machine then, with everything on its disk. Nothing lives longer than 5 hours from when it started; you can give a running machine a new end within that, or destroy it early, which gives the rest of its time back.

A key sees and stops only the machines it started, so give each developer a key of their own. By default a key may run 2 machines at once, an account 10, and an account may use 200 machine-hours in a calendar month; a running machine counts until its end. The live numbers, and what is left, are in GET /machines/catalog. Machines take SSH, the web, ping, and ports 3000 to 9999 from anywhere; they cannot send mail.

GET /api/v1/machines/catalog

What you can start, and what is left. Scope machines:read.

The sizes, images and regions on offer, the limits in force, and how much of them this key and its account are using. The live numbers, where the page above quotes the defaults.

curl
curl https://barua.tz/api/v1/machines/catalog \
-H "Authorization: Bearer $BARUA_API_KEY"
response 200
{
"sizes": [
{
"id": "nano",
"cpus": 1,
"memoryGb": 1,
"diskGb": 25,
"fitsFor": "A script, a bot, a small API."
},
{
"id": "small",
"cpus": 1,
"memoryGb": 2,
"diskGb": 50,
"fitsFor": "A web app and its database."
}
],
"images": [
{
"id": "ubuntu-24.04",
"label": "Ubuntu 24.04 LTS",
"default": true
}
],
"regions": [
{
"id": "in-bom-2",
"label": "Mumbai, India",
"default": true
}
],
"limits": {
"minMinutes": 10,
"maxMinutes": 300,
"perKey": 2,
"perAccount": 10,
"hoursPerMonth": 200
},
"usage": {
"runningForKey": 1,
"runningForAccount": 3,
"hoursThisMonth": 12.5
}
}
  • 403 machines_not_enabledMachines is switched on by Barua for the accounts it supports, and this is not one of them yet.

POST /api/v1/machines

Start a machine. Scope machines:write.

Its end is part of the request: expiresInMinutes is required, and the machine is destroyed then, with everything on its disk. It answers at once, usually with the address already known; the machine is starting until it boots, typically within a minute, and you sign in as root with one of the SSH keys you gave. There is no password.

curl
curl https://barua.tz/api/v1/machines \
-H "Authorization: Bearer $BARUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "my-test-box",
"size": "small",
"region": "in-bom-2",
"expiresInMinutes": 120,
"sshKeys": [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q you@laptop"
]
}'
response 201
{
"id": "5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21",
"name": "my-test-box",
"status": "provisioning",
"size": "small",
"cpus": 1,
"memoryGb": 2,
"diskGb": 50,
"image": "ubuntu-24.04",
"region": "in-bom-2",
"ipv4": "192.0.2.10",
"ipv6": "2001:db8::10",
"ssh": "ssh root@192.0.2.10",
"createdAt": "2026-10-20T09:00:00.000Z",
"expiresAt": "2026-10-20T11:00:00.000Z",
"minutesLeft": 120,
"destroyedAt": null,
"destroyReason": null,
"error": null
}
  • 400 invalid_jsonThe request body could not be parsed as JSON.
  • 403 machines_not_enabledMachines is switched on by Barua for the accounts it supports, and this is not one of them yet.
  • 409 machine_limit_reachedThis key, or this account, already has as many machines running as it may. Destroy one first.
  • 409 machine_budget_exhaustedThis machine would take the account past its machine-hours for the calendar month. A running machine counts until its end.
  • 422 invalid_requestThe body or query failed validation. The message names the first field that failed.
  • 422 lifetime_out_of_rangeexpiresInMinutes is under the minimum, or would take the machine past the hour cap counted from when it started.
  • 502 provider_errorThe provider refused to create the machine. Nothing is running or counted against the account; the message carries the provider's reason.
  • 503 machines_at_capacityBarua is running as many machines as it is prepared to pay for at once. Try again later.
  • 503 machines_unavailableBarua's machine provider is not connected, so nothing can start.

GET /api/v1/machines/{id}

Read one machine. Scope machines:read.

Poll this after starting one: while it boots Barua asks the provider, so status turns to running as soon as it has.

curl
curl https://barua.tz/api/v1/machines/5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21 \
-H "Authorization: Bearer $BARUA_API_KEY"
response 200
{
"id": "5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21",
"name": "my-test-box",
"status": "running",
"size": "small",
"cpus": 1,
"memoryGb": 2,
"diskGb": 50,
"image": "ubuntu-24.04",
"region": "in-bom-2",
"ipv4": "192.0.2.10",
"ipv6": "2001:db8::10",
"ssh": "ssh root@192.0.2.10",
"createdAt": "2026-10-20T09:00:00.000Z",
"expiresAt": "2026-10-20T11:00:00.000Z",
"minutesLeft": 118,
"destroyedAt": null,
"destroyReason": null,
"error": null
}
  • 403 machines_not_enabledMachines is switched on by Barua for the accounts it supports, and this is not one of them yet.
  • 404 machine_not_foundNo machine with that id was started by this key. Another key's machine answers the same, so ids cannot be probed.

GET /api/v1/machines

List the machines this key started. Scope machines:read.

Newest first, running and destroyed alike. Another key's machines are not listed, even on the same account.

curl
curl "https://barua.tz/api/v1/machines?status=active" \
-H "Authorization: Bearer $BARUA_API_KEY"
response 200
{
"data": [
{
"id": "5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21",
"name": "my-test-box",
"status": "running",
"size": "small",
"cpus": 1,
"memoryGb": 2,
"diskGb": 50,
"image": "ubuntu-24.04",
"region": "in-bom-2",
"ipv4": "192.0.2.10",
"ipv6": "2001:db8::10",
"ssh": "ssh root@192.0.2.10",
"createdAt": "2026-10-20T09:00:00.000Z",
"expiresAt": "2026-10-20T11:00:00.000Z",
"minutesLeft": 118,
"destroyedAt": null,
"destroyReason": null,
"error": null
}
],
"nextCursor": null
}
  • 403 machines_not_enabledMachines is switched on by Barua for the accounts it supports, and this is not one of them yet.
  • 422 invalid_requestThe body or query failed validation. The message names the first field that failed.
  • 422 invalid_cursorcursor is not one this list issued: pass back the nextCursor it gave you, unchanged.

POST /api/v1/machines/{id}/extend

Give a machine a new end. Scope machines:write.

Its end becomes expiresInMinutes from now. Never past the hour cap counted from when it started, so a machine cannot be kept alive by asking again. Shortening works too.

curl
curl https://barua.tz/api/v1/machines/5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21/extend \
-H "Authorization: Bearer $BARUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expiresInMinutes": 30
}'
response 200
{
"id": "5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21",
"name": "my-test-box",
"status": "running",
"size": "small",
"cpus": 1,
"memoryGb": 2,
"diskGb": 50,
"image": "ubuntu-24.04",
"region": "in-bom-2",
"ipv4": "192.0.2.10",
"ipv6": "2001:db8::10",
"ssh": "ssh root@192.0.2.10",
"createdAt": "2026-10-20T09:00:00.000Z",
"expiresAt": "2026-10-20T11:00:00.000Z",
"minutesLeft": 118,
"destroyedAt": null,
"destroyReason": null,
"error": null
}
  • 400 invalid_jsonThe request body could not be parsed as JSON.
  • 403 machines_not_enabledMachines is switched on by Barua for the accounts it supports, and this is not one of them yet.
  • 404 machine_not_foundNo machine with that id was started by this key. Another key's machine answers the same, so ids cannot be probed.
  • 409 machine_not_runningThe machine has already been destroyed, so it cannot be given more time.
  • 409 machine_budget_exhaustedThis machine would take the account past its machine-hours for the calendar month. A running machine counts until its end.
  • 422 invalid_requestThe body or query failed validation. The message names the first field that failed.
  • 422 lifetime_out_of_rangeexpiresInMinutes is under the minimum, or would take the machine past the hour cap counted from when it started.

DELETE /api/v1/machines/{id}

Destroy a machine now. Scope machines:write.

Deleted at the provider straight away, with everything on its disk, and the rest of its time given back to the account's month. Asking twice is not an error.

curl
curl -X DELETE https://barua.tz/api/v1/machines/5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21 \
-H "Authorization: Bearer $BARUA_API_KEY"
response 200
{
"id": "5b1f6d2e-8c3a-4f4e-9f61-2d7c0a9b8e21",
"name": "my-test-box",
"status": "destroyed",
"size": "small",
"cpus": 1,
"memoryGb": 2,
"diskGb": 50,
"image": "ubuntu-24.04",
"region": "in-bom-2",
"ipv4": "192.0.2.10",
"ipv6": "2001:db8::10",
"ssh": null,
"createdAt": "2026-10-20T09:00:00.000Z",
"expiresAt": "2026-10-20T11:00:00.000Z",
"minutesLeft": null,
"destroyedAt": "2026-10-20T09:40:00.000Z",
"destroyReason": "deleted",
"error": null
}
  • 403 machines_not_enabledMachines is switched on by Barua for the accounts it supports, and this is not one of them yet.
  • 404 machine_not_foundNo machine with that id was started by this key. Another key's machine answers the same, so ids cannot be probed.

Something unclear or wrong? That is a bug in these docs. Write to support@barua.tz.