Skip to main content
File routes read and write a running sandbox’s filesystem directly, without an exec. They are served by the data plane with a token, never by the control plane. Every route takes the file’s absolute path in ?path=.

Writing

PUT /sandbox/{id}/files?path= writes the request body as the file’s contents. Missing parent directories are created. The response is 201 for a new file and 200 for a replaced one. The CLI’s cp copies one regular file, and a sandbox path ending in / takes the local file’s name.
Output
The replace is atomic. A reader sees the old file or the new one, never a partial write, and an existing file keeps its mode and owner. ?directory=true with no body creates a directory.

Reading

GET /sandbox/{id}/files?path= returns the file’s bytes as application/octet-stream, with its Content-Length. HEAD returns the headers only. With the CLI, a local directory takes the sandbox file’s name, and - writes the file to stdout.
Output
A transfer interrupted midway can retain status 200 while the body is shorter than Content-Length. Compare the received byte count with Content-Length and reject a mismatch, even if the HTTP library reports a clean end of stream. Discard an incomplete download and retry the whole request. A Range header is ignored, and the whole file is returned.

Listing

?list=true returns a directory’s entries, 20 per page and at most 100. ?stat=true returns the entry of the path itself. A symbolic link is reported as a link, not followed.
Output

Renaming and Deleting

POST /sandbox/{id}/files/rename renames a path. The response is 204.
Request
The target’s parent must exist. A rename across filesystems, such as from / to /workspace, is refused with 409 cross_device. DELETE /sandbox/{id}/files?path= deletes a file or an empty directory. The response is 204. ?recursive=true deletes a directory and its contents. A non-empty directory without it is refused with 409 directory_not_empty.

Sizes

An Idempotency-Key on a PUT is accepted for bodies up to 8 MiB. A larger upload that carries one is refused with 400.

Paths

  • Format. Absolute, at most 4,096 bytes of UTF-8, not ending in . or ... An invalid path is refused with 422 invalid_path.
  • Missing. A path that does not exist is 404.
  • Kind. A write on a directory, or a directory write on a file, is refused with 409 path_type_mismatch. A read, a HEAD, or ?list=true on the wrong kind of path is refused with 422 invalid_path.
  • Reserved. Writes, renames, and deletes under /.telnyx are refused with 422 invalid_path, whether or not the directory exists.
  • Owner. File requests run as root.
Every file request counts as activity for idle_timeout. File requests to a paused sandbox are refused with 409 sandbox_paused.