> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Create, Connect, And List Machines

> Launch machines, reconnect by ID, inspect metadata, and paginate lists.

## 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.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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()
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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();
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine create --template base --vcpus 2 --memory 512 --disk 8192 --timeout 300
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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}" }
    }'
  ```
</CodeGroup>

`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](../templates/warm-pools) 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:

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine create \
    --template team/review-api:stable \
    --warm-pool twp_review_api_small \
    --warm-pool-mode prefer \
    --warm-pool-wait 1500 \
    --json
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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 }
    }'
  ```
</CodeGroup>

`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.

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  machine = Machine.connect("mch_123")
  print(machine.get_info().status)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { Machine } from "nullspace";

  const machine = await Machine.connect("mch_123");
  console.log(machine.info.status);
  ```
</CodeGroup>

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](#inspect)).

## List

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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);
  }
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine list --limit 20
  nullspace machine list --state running --json
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/machines?limit=20" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

Filter lists by state, template, or metadata:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  info = machine.get_info()
  print(info.id, info.status, info.template)
  print(info.metadata)
  print(machine.is_running())
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  const info = await machine.refresh();
  console.log(info.id, info.status, info.template);
  console.log(info.metadata);
  console.log(await machine.isRunning());
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine get mch_123 --json
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

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:

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
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.

## Related

* [Lifecycle](./lifecycle)
* [Auto-resume](./auto-resume)
* [Metrics and timeouts](./metrics-timeouts)
* [Template warm pools](../templates/warm-pools)
* [Python SDK machines](../guides/python-sdk/machines)