Read & write

Direct volume paths are absolute volume-internal paths rooted at /. Relative paths are rejected, .. cannot escape the volume root, and there is no machine cwd or user context for direct volume operations.

Read

from nullspace import Volume

volume = Volume.from_name("team-data", create_if_missing=True)

text = volume.files.read("/datasets/report.txt")
raw = volume.files.read("/datasets/report.bin", format="bytes")

nullspace volume read team-data /datasets/report.txt
nullspace volume read team-data /datasets/report.bin --encoding base64
nullspace volume cat team-data /datasets/report.txt

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/read" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets/report.txt"}'

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/read" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets/report.bin", "encoding": "base64"}'

Use cat for UTF-8 text. Use read --encoding base64 for binary data.

Write

volume.files.make_dir("/datasets")
volume.files.write("/datasets/report.txt", "ready\n")
volume.files.write("/datasets/blob.bin", b"\x00\x01")

printf "ready\n" | nullspace volume write team-data /datasets/report.txt
printf 'AAE=' | nullspace volume write team-data /datasets/blob.bin --encoding base64

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/mkdir" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets"}'

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/write" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets/report.txt", "content": "ready\n"}'

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/write" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets/blob.bin", "content": "AAE=", "encoding": "base64"}'

Batch Write

from nullspace import BatchWriteError

try:
    volume.files.write_files([
        ("/datasets/a.txt", "a\n"),
        ("/datasets/b.txt", "b\n"),
    ])
except BatchWriteError as exc:
    print(exc.successes, exc.failures)

nullspace volume write-files team-data '[["/a.txt","a\n"],["/b.txt","b\n"]]'
nullspace volume write-files team-data @files.json

There is no dedicated volume batch-write REST route; over HTTP, issue one POST /v1/volumes/{id}/files/write per file. write_files() can partially succeed before raising BatchWriteError. Inspect successes and failures before retrying.

Move, Remove, And Permissions

volume.files.rename("/datasets/report.txt", "/datasets/report-old.txt")
volume.files.set_permissions("/datasets/report-old.txt", "0644")
volume.files.remove("/datasets/report-old.txt")

nullspace volume mv team-data /datasets/report.txt /datasets/report-old.txt
nullspace volume chmod team-data /datasets/report-old.txt 0644
nullspace volume rm team-data /datasets/report-old.txt

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/rename" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"old_path": "/datasets/report.txt", "new_path": "/datasets/report-old.txt"}'

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/permissions" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets/report-old.txt", "permissions": "0644"}'

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/remove" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets/report-old.txt"}'

Search And Replace

matches = volume.files.find_files("/datasets", "ready")
paths = volume.files.search_files("/datasets", "*.txt")
result = volume.files.replace_in_files(paths, "ready", "done", dry_run=True)
print(result.dry_run, result.replacements, result.files_modified)

nullspace volume find team-data /datasets "ready"
nullspace volume search team-data /datasets "*.txt"
nullspace volume replace team-data "ready" "done" /datasets/report.txt --dry-run

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/find" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets", "pattern": "ready"}'

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/search" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"path": "/datasets", "pattern": "*.txt"}'

curl -X POST "${NULLSPACE_API_URL}/v1/volumes/vol_123/files/replace" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"files": ["/datasets/report.txt"], "pattern": "ready", "replacement": "done", "dry_run": true}'

find_files() searches file contents. search_files() matches file names. VolumeReplaceResult includes replacement counts and matched files, so dry runs can show planned changes before writing.

Watch

def on_event(event):
    print(event.type, event.path)

with volume.files.watch_dir("/", on_event=on_event, recursive=True):
    volume.files.write("/datasets/changed.txt", "changed\n")

nullspace volume watch team-data /datasets --recursive --timeout 30

Volume watch is not a plain REST call: it streams change events over the volume data plane rather than a single request/response endpoint, so there is no curl equivalent. Direct watches are opened against a concrete volume ID. If you look up a volume by name, the SDK resolves it first and then watches that ID. In multi-host deployments, mutations through another data-plane host may require a resync; clients should treat resync_required as a prompt to list or stat the watched tree again.

Async

from nullspace import AsyncVolume

volume = await AsyncVolume.from_name("team-data", create_if_missing=True)
await volume.files.write("/hello.txt", "persistent\n")
print(await volume.files.read("/hello.txt"))

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Read

Write

Batch Write

Move, Remove, And Permissions

Search And Replace

Watch

Async

​Read

​Write

​Batch Write

​Move, Remove, And Permissions

​Search And Replace

​Watch

​Async

​Related

Read

Write

Batch Write

Move, Remove, And Permissions

Search And Replace

Watch

Async

Related