Create, Connect, And List Machines

Create

Each example below is an equivalent alternative; clients do not share the same in-memory handle. The TypeScript SDK does not accept a network policy on create, so use the Python SDK, CLI, or HTTP API when you need create-time network controls.

from nullspace import Machine

machine = Machine.create(
    template="base",
    vcpus=2,
    memory_mb=512,
    disk_mb=8192,
    timeout=300,
    cwd="/workspace",
    envs={"APP_ENV": "dev"},
    metadata={"project": "docs"},
    network={"mask_request_host": "localhost:${PORT}"},
)
print(machine.id)
machine.kill()

import { Machine } from "nullspace";

const machine = await Machine.create({
  template: "base",
  vcpus: 2,
  memoryMb: 512,
  diskMb: 8192,
  timeout: 300,
  cwd: "/workspace",
  envs: { APP_ENV: "dev" },
  metadata: { project: "docs" },
});
console.log(machine.info.id);
await machine.destroy();

nullspace machine create --template base --vcpus 2 --memory 512 --disk 8192 --timeout 300

curl -X POST "${NULLSPACE_API_URL}/v1/machines" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "base",
    "vcpus": 2,
    "memory_mb": 512,
    "disk_mb": 8192,
    "timeout_ms": 300000,
    "cwd": "/workspace",
    "envs": { "APP_ENV": "dev" },
    "metadata": { "project": "docs" },
    "network": { "mask_request_host": "localhost:${PORT}" }
  }'

disk_mb sets the minimum rootfs size (MB). On cold create the disk is grown to this size before boot. Snapshot-backed templates fix their disk size at build time, so for those set the size with Template.build(..., disk_mb=...) rather than per-create — passing a larger disk_mb than the template’s built-in size is rejected.

Create From A Template Warm Pool

Use a template warm pool when many machines should start from the same ready custom template. Pass an explicit pool ID and checkout mode. The TypeScript SDK does not expose warm-pool checkout on create, so use the Python SDK, CLI, or HTTP API:

machine = Machine.create(
    template="team/review-api:stable",
    warm_pool="twp_review_api_small",
    warm_pool_mode="prefer",
    warm_pool_wait_ms=1500,
)
print(machine.get_info().warm_pool_checkout)

nullspace machine create \
  --template team/review-api:stable \
  --warm-pool twp_review_api_small \
  --warm-pool-mode prefer \
  --warm-pool-wait 1500 \
  --json

curl -X POST "${NULLSPACE_API_URL}/v1/machines" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "team/review-api:stable",
    "warm_pool": { "id": "twp_review_api_small", "mode": "prefer", "wait_ms": 1500 }
  }'

prefer may cold-fallback, require fails with warm_pool_unavailable, and bypass forces cold create. Snapshot restore, resume, fork, hibernate, and pause do not use template warm-pool checkout.

Connect

Use connect when another process created the machine or when a previous script handed you a machine ID.

machine = Machine.connect("mch_123")
print(machine.get_info().status)

import { Machine } from "nullspace";

const machine = await Machine.connect("mch_123");
console.log(machine.info.status);

If the ID points at a paused machine alias, connect() resumes the snapshot and returns a running machine handle. For a read-only lookup that does not wake paused work, use Machine.get_info_by_id("mch_123"), nullspace machine get mch_123, or GET /v1/machines/mch_123 (see Inspect).

List

page = Machine.list(limit=20)
for item in page.items:
    print(item.id, item.status, item.template)

while page.has_next:
    for item in page.next_items():
        print(item.id)

import { NullspaceClient } from "nullspace";

const client = new NullspaceClient();
const page = await client.machines.list({ limit: 20 });
for (const item of page.items) {
  console.log(item.id, item.status, item.template);
}

nullspace machine list --limit 20
nullspace machine list --state running --json

curl "${NULLSPACE_API_URL}/v1/machines?limit=20" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

Filter lists by state, template, or metadata:

from nullspace import MachineQuery

page = Machine.list(
    query=MachineQuery(template="base", metadata={"project": "docs"}),
    limit=20,
)

Use fields when you only need a compact response:

rows = Machine.list(fields=["id", "status", "template"])
for row in rows:
    print(row["id"], row["status"])

When fields is set, the SDK returns raw dictionaries instead of a MachinePaginator.

Inspect

info = machine.get_info()
print(info.id, info.status, info.template)
print(info.metadata)
print(machine.is_running())

const info = await machine.refresh();
console.log(info.id, info.status, info.template);
console.log(info.metadata);
console.log(await machine.isRunning());

nullspace machine get mch_123 --json

curl "${NULLSPACE_API_URL}/v1/machines/mch_123" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

For read-only inspection without resuming a paused machine, call Machine.get_info_by_id("mch_123"). For metrics without a handle, use Machine.get_metrics_by_id("mch_123").

Cleanup

Use a context manager for short-lived tasks:

with Machine.create(template="base") as machine:
    print(machine.commands.run("echo ready", shell=True).stdout)

For long-lived sessions, call machine.kill() or Machine.kill_by_id("mch_...") when the work is complete.

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Create, Connect, And List Machines

Create

Create From A Template Warm Pool

Connect

List

Inspect

Cleanup

​Create

​Create From A Template Warm Pool

​Connect

​List

​Inspect

​Cleanup

​Related

Create

Create From A Template Warm Pool

Connect

List

Inspect

Cleanup

Related