First Machine

Run your first hosted Nullspace machine from any laptop with Python 3.11+ and a private-beta API key.

Install the CLI

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "nullspace-sdk[cli]==1.0.0"

uv venv
source .venv/bin/activate
uv pip install "nullspace-sdk[cli]==1.0.0"

python3 -m venv .venv
source .venv/bin/activate.fish
python -m pip install --upgrade pip
python -m pip install "nullspace-sdk[cli]==1.0.0"

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install "nullspace-sdk[cli]==1.0.0"

py -3.11 -m venv .venv
.venv\Scripts\activate.bat
python -m pip install --upgrade pip
python -m pip install "nullspace-sdk[cli]==1.0.0"

PowerShell blocks activation?

Run this first, then activate again:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Save your API key

Ask the Nullspace team for a beta key, then save it with the hosted API URL:

nullspace auth login --api-url https://api.13-215-85-171.sslip.io

The command prompts for the key and stores it in your local Nullspace config — no environment variables needed for local use.

Check access

nullspace doctor

When the checks pass, doctor prints Run: nullspace quickstart.

Run the first machine

nullspace quickstart

Expected output:

Creating machine from template 'base'...
Machine ready: mch_...
hello from nullspace
hello from a machine
Preview URL: https://preview.your-nullspace-domain/.../?edge_token=...

Open the preview URL while the command waits for Enter — it serves a live HTTP server running inside your machine. Pressing Enter stops the server and destroys the machine.

The same flow in Python

The CLI quickstart runs the exact SDK flow you would write yourself. Save it locally with nullspace quickstart --write quickstart.py, or create it by hand:

quickstart.py

from nullspace import Machine

with Machine.create(template="base", timeout=300) as machine:
    print(f"Machine ready: {machine.id}")

    result = machine.commands.run("echo 'hello from nullspace'", shell=True)
    print(result.stdout.strip())

    machine.files.write("/workspace/hello.txt", "hello from a machine\n")
    print(machine.files.read("/workspace/hello.txt").strip())

    server = machine.commands.run(
        "cd /workspace && python3 -m http.server 8080 --bind 0.0.0.0",
        shell=True,
        background=True,
    )
    try:
        url = machine.get_url(8080)
        print(f"Preview URL: {url}")
        input("Open the URL, then press Enter to stop the server and destroy the machine...")
    finally:
        server.kill()

Run it from the activated environment with python quickstart.py. A few things worth noticing:

General filesystem APIs also accept valid machine-scoped absolute paths like /tmp/result.txt; /workspace remains the default mutable work tree.
The with block destroys the machine on exit. Without a context manager, call machine.kill() when you are done.
The preview URL is a signed link to a port inside the microVM — see Preview URLs.
For the command line reference and more CLI workflows, see the Python CLI Guide.

Configuration for scripts and CI

Environment variables work everywhere the CLI config does:

export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.13-215-85-171.sslip.io

The SDK and CLI also read project .env, ~/.config/nullspace/config.json, and ~/.nullspace/config.json. Explicit api_key= and base_url= arguments override local config when you need per-process values.

Optional: set up Claude Code or Codex locally

If you want Claude Code or Codex on your laptop to build with Nullspace, install the MCP extra and then the project-local agent pack:

python -m pip install "nullspace-sdk[cli,mcp]==1.0.0"
cd /path/to/your/project
nullspace docs install --agent all

This writes local agent docs (.nullspace/agent-docs/), Claude Code and Codex skills, managed CLAUDE.md/AGENTS.md blocks, and MCP config. Use --agent claude-code or --agent codex for a narrower install. The installer needs no API key, stores no secrets, and never edits user-level files.

Troubleshooting

Symptom	Check
`NULLSPACE_API_KEY is required`	Run `nullspace auth login --api-url https://api.13-215-85-171.sslip.io`, export `NULLSPACE_API_KEY`, or pass `api_key=` to `Machine.create`.
`401` or `403`	Confirm the key is active and sent as `Authorization: Bearer ...`.
Machine create times out	Increase `--timeout` or `timeout=` during private beta, or retry when capacity is available.
Preview URL does not respond	Bind the server to `0.0.0.0`, keep the background process running, then retry `machine.get_url(port)`.

Next steps

Browse recipes

Common next tasks: files, ports, fork, templates, volumes, and raw HTTP.

Run notebook-style code

Stateful Python cells, packages, charts, and artifacts.

Run an agent in a machine

Codex, Claude Code, Amp, OpenCode — or deploy your own.

Build a template

Bake dependencies once and launch repeatable machines.

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

The same flow in Python

Configuration for scripts and CI

Troubleshooting

Next steps

Browse recipes

Run notebook-style code

Run an agent in a machine

Build a template

​The same flow in Python

​Configuration for scripts and CI

​Troubleshooting

​Next steps

Browse recipes

Run notebook-style code

Run an agent in a machine

Build a template

The same flow in Python

Configuration for scripts and CI

Troubleshooting

Next steps