Get started

Quickstart

Create a machine that runs a command, stream its output, and delete it.

1Set up

Install what your language needs, then create a key on the API keys page. It is shown once.

Where a response returns an id, the cURL, TypeScript and Python samples keep it in a variable for the steps after it. Each Go sample is a program of its own: it prints the id, and the later programs read it from the environment.

curl --version | head -n 1 # 7.76 or later
jq --version # 1.6 or later

// Bun 1.1 or later, or Node 22.18 or later: global fetch, top-level await and
// streamed response bodies, with no packages. Run a sample as a .ts file.

# Python 3.9 or later
# pip install requests
import requests

// Go 1.24 or later: the samples use crypto/rand.Text.
// go run sample.go
package main

Shell

export NITROUS_KEY=nx_…

2Create a machine

The response returns once the machine is running and its command has started. The sample keeps its id as MACHINE_ID, machineId or machine_id, for the next steps; the Go program prints it: run export MACHINE_ID=… with the value. Without a size, the machine is standard.

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": "ubuntu-26.04",
  "command": ["sh", "-c", "uname -r && nproc"]
}' | jq -er '.id // error(.error)')

const createdKey = crypto.randomUUID();

const created = await fetch("https://api.nitrous.sh/v1/machines", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
    "Idempotency-Key": createdKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "image": "ubuntu-26.04",
    "command": ["sh", "-c", "uname -r && nproc"]
  }),
});
if (!created.ok) throw new Error(`Nitrous API: ${created.status} ${await created.text()}`);
const { id: machineId } = await created.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": "ubuntu-26.04",
        "command": ["sh", "-c", "uname -r && nproc"],
    },
)
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": "ubuntu-26.04",
	  "command": ["sh", "-c", "uname -r && nproc"]
	}`))
	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)
}

201Created· Abbreviated response · full object

{
  "id": "m_01m3kmnv02f4j8bdzeyt7p2fhx",
  "object": "machine",
  "image": "ubuntu-26.04",
  "state": "running",
  "size": "standard",
  "created_at": "2026-09-28T09:14:02.114Z",
  "expires_at": "2026-09-28T10:14:02.114Z",
  …
}

3Stream the output

With follow=true, the response stays open until the command exits.

curl -N "https://api.nitrous.sh/v1/machines/$MACHINE_ID/logs?follow=true" \
  --fail-with-body \
  -H "Authorization: Bearer $NITROUS_KEY"

const logs = await fetch(`https://api.nitrous.sh/v1/machines/${machineId}/logs?follow=true`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.NITROUS_KEY}`,
  },
});
if (!logs.ok) throw new Error(`Nitrous API: ${logs.status} ${await logs.text()}`);
for await (const chunk of logs.body!) process.stdout.write(chunk);

import os
import sys
import requests

r = requests.get(
    f"https://api.nitrous.sh/v1/machines/{machine_id}/logs?follow=true",
    headers={"Authorization": f"Bearer {os.environ['NITROUS_KEY']}"},
    stream=True,
)
if not r.ok:
    raise SystemExit(f"Nitrous API: {r.status_code} {r.text}")
for chunk in r.iter_content(chunk_size=None):
    sys.stdout.buffer.write(chunk)
    sys.stdout.buffer.flush()

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.MethodGet, "https://api.nitrous.sh/v1/machines/"+machineID+"/logs?follow=true", 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)
	}
}

200text/plain

6.1.128
2

4Delete the machine

A machine whose command has exited is already destroyed, unless it was created with keep_alive. DELETE returns the final state in either case.

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)
	}
}

200OK· Abbreviated response · full object

{
  "id": "m_01m3kmnv02f4j8bdzeyt7p2fhx",
  "object": "machine",
  "state": "destroyed",
  "command": {
    "status": "exited",
    "exit_code": 0,
    "exit_signal": null,
    "exited_at": "2026-09-28T09:14:02.905Z"
  },
  "destroyed_at": "2026-09-28T09:14:03.188Z",
  "destroy_reason": "command_exited",
  …
}

Run commands in a kept machine.
Build a custom image from a Dockerfile.
Retry a create: which failures to retry, and how to reconcile the rest.

Quickstart

1Set up

2Create a machine

3Stream the output

4Delete the machine

Next