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

# Recipes

> Common Nullspace tasks shown in every client — Python SDK, CLI, HTTP API, and MCP.

Each recipe shows the same task across all four ways to drive Nullspace. Pick
the tab for your client; the rest of the docs use the same pattern.

<Note>
  **MCP** exposes every CLI command as a tool (`nullspace machine create` →
  `nullspace.machine.create`), so a local coding agent runs these recipes by
  asking in natural language. See [Local MCP](../agents/local-mcp) to connect
  Codex, Claude Code, Cursor, or VS Code.
</Note>

## Create a machine

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

  machine = Machine.create(template="base", timeout=300)
  print(machine.id)
  ```

  ```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 -X POST "$NULLSPACE_API_URL/v1/machines" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"template": "base", "timeout_ms": 300000}'
  ```

  ```text MCP theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Ask your agent: "Create a Nullspace machine from the base template."
  Tool called: nullspace.machine.create  (args: --template base)
  ```
</CodeGroup>

## Run a command

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  result = machine.commands.run("echo hello && python3 --version", shell=True)
  print(result.exit_code, result.stdout)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine exec mch_123 --shell "echo hello && python3 --version"
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "$NULLSPACE_API_URL/v1/machines/mch_123/exec" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command": "echo hello && python3 --version", "shell": true}'
  ```

  ```text MCP theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Ask your agent: "In machine mch_123, run echo hello && python3 --version."
  Tool called: nullspace.machine.exec
  ```
</CodeGroup>

## Read and write files

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  machine.files.write("/workspace/hello.txt", "hi\n")
  print(machine.files.read("/workspace/hello.txt"))
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  printf "hi\n" | nullspace machine file write mch_123 /workspace/hello.txt
  nullspace machine file read mch_123 /workspace/hello.txt
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "$NULLSPACE_API_URL/v1/machines/mch_123/files/write" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"path": "/workspace/hello.txt", "content": "hi\n"}'
  ```

  ```text MCP theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Ask your agent: "Write 'hi' to /workspace/hello.txt in mch_123, then read it back."
  Tools called: nullspace.machine.file.write, nullspace.machine.file.read
  ```
</CodeGroup>

## Expose a preview URL

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  machine.commands.run(
      "cd /workspace && python3 -m http.server 8080 --bind 0.0.0.0",
      shell=True, background=True,
  )
  print(machine.get_url(8080))
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine exec mch_123 --shell \
    "cd /workspace && python3 -m http.server 8080 --bind 0.0.0.0" --background
  nullspace machine url mch_123 8080
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "$NULLSPACE_API_URL/v1/machines/mch_123/ports/8080/preview-url" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY"
  ```

  ```text MCP theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Ask your agent: "Serve /workspace on port 8080 in mch_123 and give me the preview URL."
  Tools called: nullspace.machine.exec, nullspace.machine.url
  ```
</CodeGroup>

## Fork a running machine

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  child = machine.fork()
  print(child.id)
  ```

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

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

  ```text MCP theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Ask your agent: "Fork machine mch_123."
  Tool called: nullspace.machine.fork
  ```
</CodeGroup>

## Pause and resume

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  snapshot = machine.hibernate()          # pause, persist full state
  machine = Machine.resume(snapshot.id)   # wake where it stopped
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine pause mch_123
  nullspace machine resume <snapshot-id>
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "$NULLSPACE_API_URL/v1/machines/mch_123/hibernate" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY"
  # resume targets the returned snapshot id
  curl -X POST "$NULLSPACE_API_URL/v1/machines/<snapshot-id>/resume" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY"
  ```

  ```text MCP theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Ask your agent: "Pause machine mch_123." (later) "Resume it."
  Tools called: nullspace.machine.pause, nullspace.machine.resume
  ```
</CodeGroup>

## List and clean up

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  for s in Machine.list():
      print(s.id, s.status)
  machine.kill()
  ```

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

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "$NULLSPACE_API_URL/v1/machines?state=running" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY"
  curl -X DELETE "$NULLSPACE_API_URL/v1/machines/mch_123" \
    -H "Authorization: Bearer $NULLSPACE_API_KEY"
  ```

  ```text MCP theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  Ask your agent: "List running machines, then kill mch_123."
  Tools called: nullspace.machine.list, nullspace.machine.kill
  ```
</CodeGroup>

## Go deeper

<CardGroup cols={2}>
  <Card title="Build a template" icon="layers" href="../templates/quickstart">
    Capture dependencies once and start future machines from a reusable
    template.
  </Card>

  <Card title="Mount a volume" icon="hard-drive" href="../volumes/overview">
    Persist data independently of any one machine and mount it into many runs.
  </Card>

  <Card title="Run code interpreter" icon="square-terminal" href="../code-interpreter/overview">
    Stateful notebook-style cells, package installs, and rich results.
  </Card>

  <Card title="Run an agent" icon="bot" href="../agents/overview">
    MCP, an in-machine coding-agent template, or a framework integration.
  </Card>
</CardGroup>