Guide

Build a custom image

Custom images are built from a Dockerfile, tested in a machine, and published. A custom image is private to its account: no other account can see or boot it. The images every account can boot are the base images.

1Create the image

Create an image with a name, and keep its id (img_…). API paths accept the id or the name. The name is unique in the account and cannot match a base image.

KEY=$(uuidgen)
curl -X POST https://api.nitrous.sh/v1/images \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "web-runner"
}'

const imageKey = crypto.randomUUID();

const image = await fetch("https://api.nitrous.sh/v1/images", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
    "Idempotency-Key": imageKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "web-runner"
  }),
});
if (!image.ok) throw new Error(`Nitrous API: ${image.status} ${await image.text()}`);
const imageData = await image.json();

import os
import uuid
import requests

key = str(uuid.uuid4())

r = requests.post(
    "https://api.nitrous.sh/v1/images",
    headers={
        "Authorization": f"Bearer {os.environ['NITROUS_KEY']}",
        "Idempotency-Key": key,
    },
    json={
        "name": "web-runner",
    },
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
data = r.json()

package main

import (
	"crypto/rand"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
)

func main() {
	key := rand.Text()
	req, err := http.NewRequest(http.MethodPost, "https://api.nitrous.sh/v1/images", strings.NewReader(`{
	  "name": "web-runner"
	}`))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	req.Header.Set("Idempotency-Key", key)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		var e struct {
			Code      string `json:"code"`
			Error     string `json:"error"`
			RequestID string `json:"request_id"`
		}
		_ = json.NewDecoder(res.Body).Decode(&e)
		log.Fatalf("Nitrous API: %s %s: %s (%s)", res.Status, e.Code, e.Error, e.RequestID)
	}
	if _, err := io.Copy(os.Stdout, res.Body); err != nil {
		log.Fatal(err)
	}
}

201Created

{
  "id": "img_01m3kn0phjfxka50m2f7x78fdk",
  "object": "image",
  "name": "web-runner",
  "published_build": null,
  "latest_build": null,
  "created_at": "2026-09-28T09:19:58.002Z",
  "updated_at": "2026-09-28T09:19:58.002Z"
}

2Start a build

Create a build from the Dockerfile. The sample keeps the number it returns as BUILD, buildNumber or build_number, for the steps after it; the Go program prints it: run export BUILD=… with the value.

KEY=$(uuidgen)
BUILD=$(curl -sS -X POST https://api.nitrous.sh/v1/images/web-runner/builds \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dockerfile": "FROM debian:13\nRUN apt-get update && apt-get install -y --no-install-recommends nodejs npm git\n"
}' | jq -er '.number // error(.error)')

const buildKey = crypto.randomUUID();

const build = await fetch("https://api.nitrous.sh/v1/images/web-runner/builds", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
    "Idempotency-Key": buildKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "dockerfile": "FROM debian:13\nRUN apt-get update && apt-get install -y --no-install-recommends nodejs npm git\n"
  }),
});
if (!build.ok) throw new Error(`Nitrous API: ${build.status} ${await build.text()}`);
const { number: buildNumber } = await build.json();

import os
import uuid
import requests

key = str(uuid.uuid4())

r = requests.post(
    "https://api.nitrous.sh/v1/images/web-runner/builds",
    headers={
        "Authorization": f"Bearer {os.environ['NITROUS_KEY']}",
        "Idempotency-Key": key,
    },
    json={
        "dockerfile": "FROM debian:13\nRUN apt-get update && apt-get install -y --no-install-recommends nodejs npm git\n",
    },
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
build_number = r.json()["number"]

package main

import (
	"crypto/rand"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"
)

func main() {
	key := rand.Text()
	req, err := http.NewRequest(http.MethodPost, "https://api.nitrous.sh/v1/images/web-runner/builds", strings.NewReader(`{
	  "dockerfile": "FROM debian:13\nRUN apt-get update && apt-get install -y --no-install-recommends nodejs npm git\n"
	}`))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	req.Header.Set("Idempotency-Key", key)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		var e struct {
			Code      string `json:"code"`
			Error     string `json:"error"`
			RequestID string `json:"request_id"`
		}
		_ = json.NewDecoder(res.Body).Decode(&e)
		log.Fatalf("Nitrous API: %s %s: %s (%s)", res.Status, e.Code, e.Error, e.RequestID)
	}
	var out struct {
		Number int `json:"number"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	fmt.Println(out.Number)
}

202Accepted

{
  "object": "build",
  "number": 1,
  "image": "img_01m3kn0phjfxka50m2f7x78fdk",
  "status": "queued",
  "error": null,
  "size_mib": null,
  "created_at": "2026-09-28T09:20:11.408Z",
  "started_at": null,
  "finished_at": null,
  "duration_seconds": null
}

3Wait for the build

Read the build every few seconds until its status is ready. If it is failed, its error says why and its log has the output.

curl "https://api.nitrous.sh/v1/images/web-runner/builds/$BUILD" \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY"

const polled = await fetch(`https://api.nitrous.sh/v1/images/web-runner/builds/${buildNumber}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
  },
});
if (!polled.ok) throw new Error(`Nitrous API: ${polled.status} ${await polled.text()}`);
const polledData = await polled.json();

import os
import requests

r = requests.get(
    f"https://api.nitrous.sh/v1/images/web-runner/builds/{build_number}",
    headers={"Authorization": f"Bearer {os.environ['NITROUS_KEY']}"},
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
data = r.json()

package main

import (
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	buildNumber := os.Getenv("BUILD")
	if buildNumber == "" {
		log.Fatal("set BUILD to the value an earlier step printed")
	}
	req, err := http.NewRequest(http.MethodGet, "https://api.nitrous.sh/v1/images/web-runner/builds/"+buildNumber, nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		var e struct {
			Code      string `json:"code"`
			Error     string `json:"error"`
			RequestID string `json:"request_id"`
		}
		_ = json.NewDecoder(res.Body).Decode(&e)
		log.Fatalf("Nitrous API: %s %s: %s (%s)", res.Status, e.Code, e.Error, e.RequestID)
	}
	if _, err := io.Copy(os.Stdout, res.Body); err != nil {
		log.Fatal(err)
	}
}

200OK

{
  "object": "build",
  "number": 1,
  "image": "img_01m3kn0phjfxka50m2f7x78fdk",
  "status": "ready",
  "error": null,
  "size_mib": 812,
  "created_at": "2026-09-28T09:20:11.408Z",
  "started_at": "2026-09-28T09:20:12.950Z",
  "finished_at": "2026-09-28T09:23:40.117Z",
  "duration_seconds": 207.167,
  "dockerfile": "FROM debian:13\nRUN apt-get update && apt-get install -y --no-install-recommends nodejs npm git\n"
}

4Test the build

Boot the build as name@n in a machine without a command, which stays idle, and run the test in it. The sample keeps the machine's id as MACHINE_ID, machineId or machine_id; the Go program prints it: run export MACHINE_ID=… with the value. A 200 can carry a failed command: the build passes only if exit_code is 0 and timed_out is false. Delete the machine either way.

KEY=$(uuidgen)
MACHINE_ID=$(curl -sS -X POST https://api.nitrous.sh/v1/machines \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image": "web-runner@'"$BUILD"'",
  "ttl_seconds": 600
}' | jq -er '.id // error(.error)')

const bootedKey = crypto.randomUUID();

const booted = await fetch("https://api.nitrous.sh/v1/machines", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
    "Idempotency-Key": bootedKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "image": `web-runner@${buildNumber}`,
    "ttl_seconds": 600
  }),
});
if (!booted.ok) throw new Error(`Nitrous API: ${booted.status} ${await booted.text()}`);
const { id: machineId } = await booted.json();

import os
import uuid
import requests

key = str(uuid.uuid4())

r = requests.post(
    "https://api.nitrous.sh/v1/machines",
    headers={
        "Authorization": f"Bearer {os.environ['NITROUS_KEY']}",
        "Idempotency-Key": key,
    },
    json={
        "image": f"web-runner@{build_number}",
        "ttl_seconds": 600,
    },
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
machine_id = r.json()["id"]

package main

import (
	"crypto/rand"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"
)

func main() {
	buildNumber := os.Getenv("BUILD")
	if buildNumber == "" {
		log.Fatal("set BUILD to the value an earlier step printed")
	}
	key := rand.Text()
	req, err := http.NewRequest(http.MethodPost, "https://api.nitrous.sh/v1/machines", strings.NewReader(`{
	  "image": "web-runner@`+buildNumber+`",
	  "ttl_seconds": 600
	}`))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	req.Header.Set("Idempotency-Key", key)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		var e struct {
			Code      string `json:"code"`
			Error     string `json:"error"`
			RequestID string `json:"request_id"`
		}
		_ = json.NewDecoder(res.Body).Decode(&e)
		log.Fatalf("Nitrous API: %s %s: %s (%s)", res.Status, e.Code, e.Error, e.RequestID)
	}
	var out struct {
		ID string `json:"id"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	fmt.Println(out.ID)
}

curl -X POST "https://api.nitrous.sh/v1/machines/$MACHINE_ID/exec" \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "command": ["node", "--version"],
  "timeout_seconds": 60
}'

const ran = await fetch(`https://api.nitrous.sh/v1/machines/${machineId}/exec`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "command": ["node", "--version"],
    "timeout_seconds": 60
  }),
});
if (!ran.ok) throw new Error(`Nitrous API: ${ran.status} ${await ran.text()}`);
const ranData = await ran.json();

import os
import requests

r = requests.post(
    f"https://api.nitrous.sh/v1/machines/{machine_id}/exec",
    headers={"Authorization": f"Bearer {os.environ['NITROUS_KEY']}"},
    json={
        "command": ["node", "--version"],
        "timeout_seconds": 60,
    },
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
data = r.json()

package main

import (
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
)

func main() {
	machineID := os.Getenv("MACHINE_ID")
	if machineID == "" {
		log.Fatal("set MACHINE_ID to the value an earlier step printed")
	}
	req, err := http.NewRequest(http.MethodPost, "https://api.nitrous.sh/v1/machines/"+machineID+"/exec", strings.NewReader(`{
	  "command": ["node", "--version"],
	  "timeout_seconds": 60
	}`))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		var e struct {
			Code      string `json:"code"`
			Error     string `json:"error"`
			RequestID string `json:"request_id"`
		}
		_ = json.NewDecoder(res.Body).Decode(&e)
		log.Fatalf("Nitrous API: %s %s: %s (%s)", res.Status, e.Code, e.Error, e.RequestID)
	}
	if _, err := io.Copy(os.Stdout, res.Body); err != nil {
		log.Fatal(err)
	}
}

200OK· Abbreviated response · full object

{
  "object": "exec_result",
  "exec_id": "x-d8144042000c",
  "exit_code": 0,
  "exit_signal": null,
  "timed_out": false,
  …
}

curl -X DELETE "https://api.nitrous.sh/v1/machines/$MACHINE_ID" \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY"

const deleted = await fetch(`https://api.nitrous.sh/v1/machines/${machineId}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
  },
});
if (!deleted.ok) throw new Error(`Nitrous API: ${deleted.status} ${await deleted.text()}`);
const deletedData = await deleted.json();

import os
import requests

r = requests.delete(
    f"https://api.nitrous.sh/v1/machines/{machine_id}",
    headers={"Authorization": f"Bearer {os.environ['NITROUS_KEY']}"},
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
data = r.json()

package main

import (
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	machineID := os.Getenv("MACHINE_ID")
	if machineID == "" {
		log.Fatal("set MACHINE_ID to the value an earlier step printed")
	}
	req, err := http.NewRequest(http.MethodDelete, "https://api.nitrous.sh/v1/machines/"+machineID, nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		var e struct {
			Code      string `json:"code"`
			Error     string `json:"error"`
			RequestID string `json:"request_id"`
		}
		_ = json.NewDecoder(res.Body).Decode(&e)
		log.Fatalf("Nitrous API: %s %s: %s (%s)", res.Status, e.Code, e.Error, e.RequestID)
	}
	if _, err := io.Copy(os.Stdout, res.Body); err != nil {
		log.Fatal(err)
	}
}

5Publish the build

Publish a build only after it passed. This program does steps 4 and 5 together: it runs the test, requires exit_code 0, deletes the test machine whatever the outcome, and publishes the build only on success. Run it with BUILD set to the number from step 2 (export BUILD in a shell). web-runner then boots the build; publishing another build repoints the name, and running machines are unaffected.

set -euo pipefail
: "${BUILD:?set BUILD to the build number}"
AUTH="Authorization: Bearer $NITROUS_KEY"
JSON="Content-Type: application/json"

MACHINE_ID=""
delete_machine() {
  if [ -n "$MACHINE_ID" ]; then
    curl -sS --fail-with-body -X DELETE "https://api.nitrous.sh/v1/machines/$MACHINE_ID" \
      -H "$AUTH" -o /dev/null || echo "could not delete $MACHINE_ID" >&2
    MACHINE_ID=""
  fi
}
trap delete_machine EXIT # whatever happens below

BOOT_KEY=$(uuidgen)
MACHINE_ID=$(curl -sS --fail-with-body -X POST https://api.nitrous.sh/v1/machines \
  -H "$AUTH" -H "$JSON" -H "Idempotency-Key: $BOOT_KEY" \
  -d "{\"image\": \"web-runner@$BUILD\", \"ttl_seconds\": 600}" |
  jq -er '.id // error(.error)')

RESULT=$(curl -sS --fail-with-body -X POST "https://api.nitrous.sh/v1/machines/$MACHINE_ID/exec" \
  -H "$AUTH" -H "$JSON" -d '{ "command": ["node", "--version"], "timeout_seconds": 60 }')
# a 200 can carry a failed command: the exit code decides
if ! jq -e '.exit_code == 0 and .timed_out == false' <<<"$RESULT" >/dev/null; then
  echo "test failed: $RESULT" >&2
  exit 1
fi
delete_machine

PUBLISH_KEY=$(uuidgen)
curl -sS --fail-with-body -X POST https://api.nitrous.sh/v1/images/web-runner/publish \
  -H "$AUTH" -H "$JSON" -H "Idempotency-Key: $PUBLISH_KEY" \
  -d "{\"build\": $BUILD}"

const api = "https://api.nitrous.sh";
const build = process.env.BUILD;
if (!build) throw new Error("set BUILD to the build number");

async function call(method: string, path: string, body?: unknown, key?: string) {
  const res = await fetch(api + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.NITROUS_KEY}`,
      "Content-Type": "application/json",
      ...(key && { "Idempotency-Key": key }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (!res.ok) throw new Error(`Nitrous API: ${res.status} ${await res.text()}`);
  return res.json();
}

const bootKey = crypto.randomUUID();
const publishKey = crypto.randomUUID();

const { id } = await call("POST", "/v1/machines", { image: `web-runner@${build}`, ttl_seconds: 600 }, bootKey);
try {
  const result = await call("POST", `/v1/machines/${id}/exec`, { command: ["node","--version"], timeout_seconds: 60 });
  // a 200 can carry a failed command: the exit code decides
  if (result.exit_code !== 0 || result.timed_out) throw new Error(`test failed: ${JSON.stringify(result)}`);
} finally {
  // the test machine goes whatever the test did
  await call("DELETE", `/v1/machines/${id}`).catch((e) => console.error(`could not delete ${id}`, e));
}

console.log(await call("POST", "/v1/images/web-runner/publish", { build: Number(build) }, publishKey));

import os
import uuid
import requests

API = "https://api.nitrous.sh"
build = os.environ["BUILD"]  # the build number from the build step


def call(method, path, body=None, key=None):
    headers = {"Authorization": f"Bearer {os.environ['NITROUS_KEY']}"}
    if key:
        headers["Idempotency-Key"] = key
    r = requests.request(method, API + path, headers=headers, json=body, timeout=200)
    if not r.ok:
        raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
    return r.json()


boot_key = str(uuid.uuid4())
publish_key = str(uuid.uuid4())

machine = call("POST", "/v1/machines", {"image": f"web-runner@{build}", "ttl_seconds": 600}, boot_key)
try:
    result = call("POST", f"/v1/machines/{machine['id']}/exec", {"command": ["node", "--version"], "timeout_seconds": 60})
    # a 200 can carry a failed command: the exit code decides
    if result["exit_code"] != 0 or result["timed_out"]:
        raise SystemExit(f"test failed: {result}")
finally:
    # the test machine goes whatever the test did
    try:
        call("DELETE", f"/v1/machines/{machine['id']}")
    except SystemExit as e:
        print(f"could not delete {machine['id']}: {e}")

print(call("POST", "/v1/images/web-runner/publish", {"build": int(build)}, publish_key))

package main

import (
	"bytes"
	"crypto/rand"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strconv"
)

const api = "https://api.nitrous.sh"

// call sends one request and decodes the JSON answer into out (nil: ignored).
func call(method, path string, body, out any, key string) error {
	var reader io.Reader
	if body != nil {
		raw, err := json.Marshal(body)
		if err != nil {
			return err
		}
		reader = bytes.NewReader(raw)
	}
	req, err := http.NewRequest(method, api+path, reader)
	if err != nil {
		return err
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	req.Header.Set("Content-Type", "application/json")
	if key != "" {
		req.Header.Set("Idempotency-Key", key)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return err
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		text, _ := io.ReadAll(res.Body)
		return fmt.Errorf("Nitrous API: %s: %s", res.Status, text)
	}
	if out == nil {
		return nil
	}
	return json.NewDecoder(res.Body).Decode(out)
}

func run(build int) error {
	bootKey := rand.Text()

	var machine struct {
		ID string `json:"id"`
	}
	boot := map[string]any{"image": fmt.Sprintf("web-runner@%d", build), "ttl_seconds": 600}
	if err := call("POST", "/v1/machines", boot, &machine, bootKey); err != nil {
		return err
	}
	// the test machine goes whatever the test did
	defer func() {
		if derr := call("DELETE", "/v1/machines/"+machine.ID, nil, nil, ""); derr != nil {
			log.Printf("could not delete %s: %v", machine.ID, derr)
		}
	}()

	var result struct {
		ExitCode *int   `json:"exit_code"`
		TimedOut bool   `json:"timed_out"`
		Stderr   string `json:"stderr"`
	}
	test := map[string]any{"command": []string{"node", "--version"}, "timeout_seconds": 60}
	if err := call("POST", "/v1/machines/"+machine.ID+"/exec", test, &result, ""); err != nil {
		return err
	}
	// a 200 can carry a failed command: the exit code decides
	if result.ExitCode == nil || *result.ExitCode != 0 || result.TimedOut {
		return fmt.Errorf("test failed (timed out: %t): %s", result.TimedOut, result.Stderr)
	}
	return nil
}

func main() {
	build, err := strconv.Atoi(os.Getenv("BUILD")) // the build number from the build step
	if err != nil {
		log.Fatal("set BUILD to the build number")
	}
	if err := run(build); err != nil {
		log.Fatal(err)
	}
	// reached only when the test passed
	publishKey := rand.Text()
	var image map[string]any
	if err := call("POST", "/v1/images/web-runner/publish", map[string]any{"build": build}, &image, publishKey); err != nil {
		log.Fatal(err)
	}
	fmt.Println(image)
}

200OK

{
  "id": "img_01m3kn0phjfxka50m2f7x78fdk",
  "object": "image",
  "name": "web-runner",
  "published_build": 1,
  "latest_build": {
    "number": 1,
    "status": "ready"
  },
  "created_at": "2026-09-28T09:19:58.002Z",
  "updated_at": "2026-09-28T09:24:05.311Z"
}

6Boot the image

Boot the image by name with a command, then stream its output and delete the machine with the id the sample keeps, as in the quickstart.

KEY=$(uuidgen)
MACHINE_ID=$(curl -sS -X POST https://api.nitrous.sh/v1/machines \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "image": "web-runner",
  "command": ["node", "--version"],
  "ttl_seconds": 600
}' | jq -er '.id // error(.error)')

const startedKey = crypto.randomUUID();

const started = await fetch("https://api.nitrous.sh/v1/machines", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
    "Idempotency-Key": startedKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "image": "web-runner",
    "command": ["node", "--version"],
    "ttl_seconds": 600
  }),
});
if (!started.ok) throw new Error(`Nitrous API: ${started.status} ${await started.text()}`);
const { id: machineId } = await started.json();

import os
import uuid
import requests

key = str(uuid.uuid4())

r = requests.post(
    "https://api.nitrous.sh/v1/machines",
    headers={
        "Authorization": f"Bearer {os.environ['NITROUS_KEY']}",
        "Idempotency-Key": key,
    },
    json={
        "image": "web-runner",
        "command": ["node", "--version"],
        "ttl_seconds": 600,
    },
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
machine_id = r.json()["id"]

package main

import (
	"crypto/rand"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"
)

func main() {
	key := rand.Text()
	req, err := http.NewRequest(http.MethodPost, "https://api.nitrous.sh/v1/machines", strings.NewReader(`{
	  "image": "web-runner",
	  "command": ["node", "--version"],
	  "ttl_seconds": 600
	}`))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NITROUS_KEY"))
	req.Header.Set("Idempotency-Key", key)
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		var e struct {
			Code      string `json:"code"`
			Error     string `json:"error"`
			RequestID string `json:"request_id"`
		}
		_ = json.NewDecoder(res.Body).Decode(&e)
		log.Fatalf("Nitrous API: %s %s: %s (%s)", res.Status, e.Code, e.Error, e.RequestID)
	}
	var out struct {
		ID string `json:"id"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	fmt.Println(out.ID)
}

What a build does

A build runs docker build on the Dockerfile in a standard-size machine with a 40 GiB disk (or the largest disk tier the account's limit allows, if smaller) in the account, and converts the result into a machine image. The build machine is billed like any other, per second: $0.15324 an hour with the 40 GiB disk (see Disk). It counts toward the account's machine limit while it runs, and appears on the Usage page as image build. It is excluded from machine lists and is not accessible through exec, logs or a terminal; its output is the build log.

Image configuration

The Dockerfile's ENV, WORKDIR and USER apply to every machine booted from the image: to its command, to exec and to the terminal. A request's env overrides variables of the same name, and its cwd overrides WORKDIR. With USER, the command, exec and the terminal run as that user, with its groups and HOME; install anything that needs root in the Dockerfile. A USER not in the image's /etc/passwd fails the build. Variable names consist of letters, digits and _, and do not start with a digit. CMD and ENTRYPOINT are not run: a machine runs the command it is created with. Dockerfiles and build logs are kept for the image's lifetime, and ENV values are part of the image. Don't put secrets in them.

Bring your own image

For anything that needs local files, build the image yourself, locally or in CI, with docker build --platform linux/amd64, and push it to a registry. Then create a build whose Dockerfile is one line: FROM ghcr.io/you/app:tag. Public registries only.

Commands run as argv, so the image needs no shell. A shell (/bin/sh) is needed only for sh -c commands and the terminal.

Limits

10 images per account; 2 builds running at once.
Dockerfiles of at most 64 KiB. A build is stopped after 30 minutes; the image content must fit in 10 GiB.
Build logs: the last 1 MiB is retained once the build ends. See Stream build logs.
No build context: COPY and ADD of local files are rejected. Use RUN curl or git clone, or bring your own image.
linux/amd64. Public registries only.
Any Linux image boots, from any base, FROM scratch included: nothing needs to be installed. Commands and exec run as argv, with no shell; sh -c and the terminal need a shell (/bin/sh) in the image. An image whose /sbin/init is systemd boots systemd.

A machine booted from a custom image can use any size, with a disk of at least 10 GiB.