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

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"
Run this first, then activate again:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
2

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

Check access

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

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

SymptomCheck
NULLSPACE_API_KEY is requiredRun 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 403Confirm the key is active and sent as Authorization: Bearer ....
Machine create times outIncrease --timeout or timeout= during private beta, or retry when capacity is available.
Preview URL does not respondBind 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.