Skip to main content
Run your first hosted Nullspace sandbox 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]==0.1.9"
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 sandbox

nullspace quickstart
Expected output:
Creating sandbox from template 'base'...
Sandbox ready: sb_...
hello from nullspace
hello from a sandbox
Preview URL: https://api.your-nullspace-domain/__ns-edge/sandboxes/sb_.../ports/8080/?edge_token=...
Open the preview URL while the command waits for Enter — it serves a live HTTP server running inside your sandbox. Pressing Enter stops the server and destroys the sandbox.

​
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 Sandbox

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

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

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

    server = sandbox.commands.run(
        "cd /workspace && python3 -m http.server 8080 --bind 0.0.0.0",
        shell=True,
        background=True,
    )
    try:
        url = sandbox.get_url(8080)
        print(f"Preview URL: {url}")
        input("Open the URL, then press Enter to stop the server and destroy the sandbox...")
    finally:
        server.kill()
Run it from the activated environment with python quickstart.py. A few things worth noticing:
  • /workspace is the default mutable work tree; other sandbox-scoped absolute paths like /tmp/result.txt work too.
  • The with block destroys the sandbox on exit. Without a context manager, call sandbox.kill() when you are done.
  • The preview URL is a signed link to a port inside the microVM — see Preview URLs.

​
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]==0.1.9"
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 Sandbox.create.
401 or 403Confirm the key is active and sent as Authorization: Bearer ....
Sandbox 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 sandbox.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 sandbox

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

Build a template

Bake dependencies once and launch repeatable sandboxes.