> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem

> Read, write, upload, download, search, and watch machine files.

Filesystem APIs operate on paths inside a machine. 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 machine-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 machine control metadata and transfer state.

## Quick Example

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import Machine

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

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { Machine } from "nullspace";

  await using machine = await Machine.create({ template: "base" });
  await machine.files.write("/workspace/hello.txt", "hello\n");
  console.log(await machine.files.read("/workspace/hello.txt"));
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  printf "hello\n" | nullspace machine file write mch_123 /workspace/hello.txt
  nullspace machine file read mch_123 /workspace/hello.txt
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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": "hello\n"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/files/read" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/workspace/hello.txt"}'
  ```
</CodeGroup>

## Choose A File Operation

| Need                                        | Use                                                           |
| ------------------------------------------- | ------------------------------------------------------------- |
| Write small in-memory content               | `machine.files.write(...)` or `write_files(...)`              |
| Read text or bytes                          | `machine.files.read(..., format="text")` or `format="bytes"`  |
| Inspect paths                               | `list()`, `info()`, and `exists()`                            |
| Move, create, chmod, or remove              | `rename()`, `make_dir()`, `set_permissions()`, and `remove()` |
| Upload local files or directories           | [Uploads](./filesystem/uploads)                               |
| Download files, directories, or signed URLs | [Downloads](./filesystem/downloads)                           |
| Find or replace content                     | [Search and watch](./filesystem/search-watch)                 |

## Inspect And Mutate

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  entries = machine.files.list("/workspace")
  info = machine.files.info("/workspace/hello.txt")
  exists = machine.files.exists("/workspace/hello.txt")
  print(entries, info.size, exists)

  machine.files.make_dir("/workspace/archive")
  machine.files.rename("/workspace/hello.txt", "/workspace/archive/hello.txt")
  machine.files.set_permissions("/workspace/archive/hello.txt", "0644")
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  const entries = await machine.files.list("/workspace");
  const info = await machine.files.info("/workspace/hello.txt");
  const exists = await machine.files.exists("/workspace/hello.txt");
  console.log(entries, info.size, exists);

  await machine.files.makeDir("/workspace/archive");
  await machine.files.rename("/workspace/hello.txt", "/workspace/archive/hello.txt");
  await machine.files.setPermissions("/workspace/archive/hello.txt", "0644");
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine file list mch_123 /workspace --depth 1 --json
  nullspace machine file info mch_123 /workspace/hello.txt
  nullspace machine file exists mch_123 /workspace/hello.txt
  nullspace machine file mkdir mch_123 /workspace/archive
  nullspace machine file mv mch_123 /workspace/hello.txt /workspace/archive/hello.txt
  nullspace machine file chmod mch_123 /workspace/archive/hello.txt 0644
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X GET "${NULLSPACE_API_URL}/v1/machines/mch_123/files?path=/workspace&depth=1" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/files/info" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/workspace/hello.txt"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/files/exists" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/workspace/hello.txt"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/files/mkdir" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/workspace/archive"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/files/rename" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"old_path": "/workspace/hello.txt", "new_path": "/workspace/archive/hello.txt"}'

  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/files/permissions" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"path": "/workspace/archive/hello.txt", "permissions": "0644"}'
  ```
</CodeGroup>

Use `depth=0` for the immediate directory only or a larger depth to include
nested paths.

## Batch Write

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  machine.files.write_files([
      ("/workspace/a.txt", "a\n"),
      ("/workspace/b.txt", b"b\n"),
  ])
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine file write-files mch_123 '[["/workspace/a.txt","a\n"],["/workspace/b.txt","b\n"]]'
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # batch-write is a multipart request: a JSON `manifest` part plus one part per file field.
  printf 'a\n' > a.txt
  printf 'b\n' > b.txt
  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/files/batch-write" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -F 'manifest={"files":[{"path":"/workspace/a.txt","field":"file0"},{"path":"/workspace/b.txt","field":"file1"}]}' \
    -F "file0=@a.txt" \
    -F "file1=@b.txt"
  ```
</CodeGroup>

`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()`](./filesystem/uploads).

## Related

* [Machines](./machines/overview)
* [Commands](./commands/overview)
* [Python SDK filesystem](./guides/python-sdk/filesystem)