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
?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
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
/ 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 with422 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, aHEAD, or?list=trueon the wrong kind of path is refused with422 invalid_path. - Reserved. Writes, renames, and deletes under
/.telnyxare refused with422 invalid_path, whether or not the directory exists. - Owner. File requests run as
root.
idle_timeout. File requests to a paused sandbox are refused with 409 sandbox_paused.