Skip to main content

​
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()
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)
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)
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)
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())
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.