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

> Create Nullspace machines from templates, snapshots, and volumes with the CLI.

Use `nullspace machine create` to boot a machine from a template or reusable
snapshot. The command returns the machine ID and connection metadata.

## Create From A Template

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create --template base
```

Pass `--json` when you want the full response:

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create --template base --json
```

## Use A Template Warm Pool

Pass `--warm-pool` when a machine should try to claim ready capacity from a
[template warm pool](../templates/warm-pools):

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

Use `--warm-pool-mode require` for latency-sensitive work that should fail with
`warm_pool_unavailable` instead of cold creating when no matching ready
instance is available. Use `--warm-pool-mode bypass` to force a cold create.

## Working Directory, Environment, And Metadata

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create \
  --template base \
  --cwd /workspace \
  --env API_MODE=test \
  --env-json '{"TRACE":"1"}' \
  --metadata purpose=quickstart \
  --metadata-json '{"team":"eval"}'
```

The default mutable workspace for repo-style flows is `/workspace`, but commands
and file APIs can use other absolute paths inside the machine.

## Timeouts And Auto-Resume

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create \
  --template base \
  --timeout 300 \
  --on-timeout pause \
  --auto-resume
```

Timeout actions control what happens when a machine idles. Prefer
`--on-timeout pause` at create time when the machine should hibernate instead
of being destroyed, especially with `--auto-resume`. The lower-level
`--timeout-action hibernate` flag maps directly to the API `timeout_action`
field; use it only when you intentionally need that raw field. For an existing
machine, use `nullspace machine timeout set ... --action hibernate`.

## Create From A Snapshot

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create --snapshot-id snap_123 --timeout 300
```

Snapshots are reusable baselines. They are different from fork, which branches a
running machine immediately.

## Attach Volumes

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create \
  --template base \
  --volume ref=team-data,mount=/data \
  --volume ref=read-models,mount=/models,ro=true
```

Use volumes when multiple machines need durable shared files.

## Networking And Desktop Options

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create --template base --no-internet-access
nullspace machine create --template base --network-json '{"allow_out":["203.0.113.0/24"]}'
nullspace machine create --template desktop --resolution 1280x720 --dpi 144 --display :1
```

`allow_out` entries are CIDR ranges. Desktop create options are only valid for
desktop templates.

## Idempotent Retries

```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
nullspace machine create \
  --template base \
  --idempotency-key setup-run-001
```

Use an idempotency key when retrying a create request from automation.

## Related

* [Machines](../machines/overview)
* [Template Warm Pools](../templates/warm-pools)
* [Snapshots](../machines/snapshots)
* [Volumes](../volumes/overview)
* [Desktop Automation](../desktop/automation)