Skip to main content
read, readStream and write use the API’s file routes (GET /v1/machines/{id}/files/content and PUT /v1/machines/{id}/files), the path instabox cp takes. They need the same scope as commands. A file can be up to 5 GiB (MAX_UPLOAD_BYTES). list, exists and remove run as commands. Relative paths start at HOME, /data/home, on the persistent disk.

​
files.read

Read a file into memory, as UTF-8 text, or as bytes with { format: 'bytes' }.
A file over maxBytes (default 10 MiB, MAX_FILE_BYTES) throws file_too_large. Pass a larger maxBytes, or use readStream. A text read of a file that is not UTF-8 throws not_utf8.

​
files.readStream

Read a file of any size as a stream, in bounded memory.
Returns a ReadableStream<Uint8Array> that also works with for await. In Node, Readable.fromWeb(stream) makes it a Node stream. A missing file or a directory throws not_found before any byte. A stream that ends short of the file’s size errors with file_changed.

​
files.write

Write a file: create its parent directories and replace the file atomically.
data is a string, bytes (Uint8Array, Buffer, ArrayBuffer) or a stream: a Node Readable, a web ReadableStream, or an async iterable of chunks. A stream is sent as it is read, so memory stays flat. The SDK checks the size and SHA-256 the server reports. Returns { path }. Writing to a directory throws is_a_directory. An error from your stream throws source_error, and the file keeps its old content. Past 5 GiB the server answers too_large.

​
files.upload

Upload the contents of a local directory into remoteDir, as one gzipped tar. This is what instabox push does.
  • In a git work tree, only the files git tracks go up. all: true adds untracked files that git does not ignore. git: false sends everything under the directory.
  • Outside a git work tree, everything goes up, dot files and empty directories included.
  • Symlinks stay symlinks, and file modes are kept.
Returns { path, files, bytes }: the machine directory, the regular files sent and the archive size. A missing local directory throws local_not_found.

​
files.download

Download a machine directory into localDir, as one gzipped tar. This is what instabox pull does.
Everything under remoteDir comes, dot files and empty directories included. Returns { path, remotePath, files, bytes }. A missing machine directory throws not_found. upload and download need Node.js, Bun or Deno. In a browser or a Worker they throw unsupported. Other errors: local_io_error (the local disk), not_a_directory (a file where a directory was expected) and transfer_failed (tar failed in the machine).

​
files.list

List a directory. The list is not recursive.
Returns { name, path, type } entries, with type 'file' or 'dir'.

​
files.remove

Delete a file, or a directory recursively.
A missing path is not an error.

​
files.exists

Check whether a path exists.