Skip to main content
Filesystem APIs operate on paths inside a sandbox. Use them for small direct reads and writes, large file transfers, generated artifacts, repository files, and agent workspace inspection. /workspace is the default mutable work tree for agent and repo-style flows. General filesystem APIs also accept valid sandbox-scoped absolute paths such as /tmp/result.txt, /data/model.bin, /context/input.json, and /srv/app/config.json. Avoid writing to Nullspace runtime-managed paths under /workspace/.nullspace; they are reserved for sandbox control metadata and transfer state.

​
Quick Example

from nullspace import Sandbox

with Sandbox.create(template="base") as sandbox:
    sandbox.files.write("/workspace/hello.txt", "hello\n")
    print(sandbox.files.read("/workspace/hello.txt"))

​
Choose A File Operation

NeedUse
Write small in-memory contentsandbox.files.write(...) or write_files(...)
Read text or bytessandbox.files.read(..., format="text") or format="bytes"
Inspect pathslist(), info(), and exists()
Move, create, chmod, or removerename(), make_dir(), set_permissions(), and remove()
Upload local files or directoriesUploads
Download files, directories, or signed URLsDownloads
Find or replace contentSearch and watch

​
Inspect And Mutate

entries = sandbox.files.list("/workspace")
info = sandbox.files.info("/workspace/hello.txt")
exists = sandbox.files.exists("/workspace/hello.txt")
print(entries, info.size, exists)

sandbox.files.make_dir("/workspace/archive")
sandbox.files.rename("/workspace/hello.txt", "/workspace/archive/hello.txt")
sandbox.files.set_permissions("/workspace/archive/hello.txt", "0644")
Use depth=0 for the immediate directory only or a larger depth to include nested paths.

​
Batch Write

sandbox.files.write_files([
    ("/workspace/a.txt", "a\n"),
    ("/workspace/b.txt", b"b\n"),
])
write_files() is best for small in-memory files. For larger local files, directories, resumable transfers, or progress events, use upload_file() and upload_dir().