Recipes

from nullspace import Machine

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

nullspace machine create --template base --json

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}'

Ask your agent: "Create a Nullspace machine from the base template."
Tool called: nullspace.machine.create  (args: --template base)

result = machine.commands.run("echo hello && python3 --version", shell=True)
print(result.exit_code, result.stdout)

nullspace machine exec mch_123 --shell "echo hello && python3 --version"

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}'

Ask your agent: "In machine mch_123, run echo hello && python3 --version."
Tool called: nullspace.machine.exec

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

printf "hi\n" | nullspace machine file write mch_123 /workspace/hello.txt
nullspace machine file read mch_123 /workspace/hello.txt

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"}'

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

machine.commands.run(
    "cd /workspace && python3 -m http.server 8080 --bind 0.0.0.0",
    shell=True, background=True,
)
print(machine.get_url(8080))

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

curl -X POST "$NULLSPACE_API_URL/v1/machines/mch_123/ports/8080/preview-url" \
  -H "Authorization: Bearer $NULLSPACE_API_KEY"

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

child = machine.fork()
print(child.id)

nullspace machine fork mch_123 --json

curl -X POST "$NULLSPACE_API_URL/v1/machines/mch_123/fork" \
  -H "Authorization: Bearer $NULLSPACE_API_KEY"

Ask your agent: "Fork machine mch_123."
Tool called: nullspace.machine.fork

snapshot = machine.hibernate()          # pause, persist full state
machine = Machine.resume(snapshot.id)   # wake where it stopped

nullspace machine pause mch_123
nullspace machine resume <snapshot-id>

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"

Ask your agent: "Pause machine mch_123." (later) "Resume it."
Tools called: nullspace.machine.pause, nullspace.machine.resume

for s in Machine.list():
    print(s.id, s.status)
machine.kill()

nullspace machine list --state running
nullspace machine kill mch_123

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"

Ask your agent: "List running machines, then kill mch_123."
Tools called: nullspace.machine.list, nullspace.machine.kill