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

> Start a new hosted machine from a template.

Create allocates a machine from a template, applies CPU, memory, timeout,
environment, metadata, network, desktop, and volume options, and returns a
machine ID once the runtime is ready to accept work.

## What state changes

* A new machine enters the running set for your API key.
* Template runtime defaults and create-time overrides become the machine's
  initial process and filesystem environment.
* Optional public traffic credentials are minted for exposed ports.

## Usage

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

  with Machine.create(template="base", timeout=300) as machine:
      print(machine.id)
      result = machine.commands.run("pwd", shell=True)
      print(result.stdout.strip())
  ```

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

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -fsS -X POST \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-${USER}-$(date +%s)" \
    -d '{"template":"base","vcpus":2,"memory_mb":512,"timeout_ms":300000}' \
    "${NULLSPACE_API_URL}/v1/machines"
  ```
</CodeGroup>

API reference: [createMachine](../api-reference) (`POST /v1/machines`).

Guide: [Machines](../guides/python-sdk/machines). Example:
[Examples](../examples).