Work with files - Namespace Documentation

Use devbox.fs to transfer files between the local machine and a Devbox, read and write bytes, and manage remote files and directories.

Filesystem operations start a stopped Devbox automatically. Relative remote paths are passed unchanged to the Devbox’s SFTP or command session. Use absolute paths when the location must be unambiguous. The SDK caches the connection and SFTP channel for reuse.

`fs.upload()`

Upload one local file to the Devbox. This method does not upload directories.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.fs.upload("./package.json", "/workspace/package.json");

API reference

upload(localPath: string, remotePath: string, options?: TransferOptions): Promise<void>

Arguments and options

string

required

A path on the machine running the SDK. Relative paths resolve from that process’s current working directory.

string

required

The destination file path in the Devbox.

TransferOptions

Transfer and operation controls.

Hide properties

(transferredBytes: number, totalBytes: number) => void

Called during transfer with the cumulative bytes transferred and total file size. It is not called when omitted.

AbortSignal

Cancels the operation when aborted.

number

Total activation, connection, and transfer budget in milliseconds. There is no default timeout. The value must be finite and non-negative.

`fs.download()`

Download one remote file to the local filesystem. This method does not download directories.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.fs.download("/workspace/results.json", "./results.json", {
  onProgress: (transferred, total) => console.log(`${transferred}/${total}`),
});

API reference

download(remotePath: string, localPath: string, options?: TransferOptions): Promise<void>

Arguments and options

string

required

The source file in the Devbox.

string

required

A local destination path. Relative paths resolve from the SDK process’s current working directory.

TransferOptions

The same onProgress, signal, and timeoutMs fields as upload().

`fs.copy()`

Copy a file or directory within the Devbox. The operation invokes remote cp and rejects when it exits unsuccessfully.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.fs.copy("/workspace/src", "/workspace/src-backup", { recursive: true });

API reference

copy(sourcePath: string, destinationPath: string, options?: CopyOptions): Promise<void>

Arguments and options

string

required

The remote source path.

string

required

The remote destination path.

CopyOptions

Hide properties

boolean

default:"false"

Passes -R to cp, allowing directories to be copied recursively.

AbortSignal

Cancels the operation when aborted.

number

Total operation budget in milliseconds. There is no default timeout.

`fs.readFile()`

Read an entire remote file into memory as raw bytes. The SDK does not decode its contents.

Example

const devbox = await client.devboxes.get("sdk-example");
const text = new TextDecoder().decode(await devbox.fs.readFile("/workspace/message.txt"));

API reference

readFile(remotePath: string, options?: OperationOptions): Promise<Uint8Array>

Arguments and options

string

required

The remote file to read.

OperationOptions

Optional signal and timeoutMs operation controls.

Return value

A Uint8Array containing the file’s unmodified bytes.

`fs.writeFile()`

Write a string or raw bytes to a remote file. The file is created or truncated. Strings are written as UTF-8.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.fs.writeFile("/workspace/config.json", JSON.stringify({ enabled: true }), { mode: 0o600 });

API reference

writeFile(remotePath: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>

Arguments and options

string

required

The remote file to create or replace.

string | Uint8Array

required

UTF-8 text or bytes to write.

WriteFileOptions

Hide properties

number

POSIX permission bits, such as 0o600. When omitted, the SFTP server applies its default permissions and umask.

AbortSignal

Cancels the operation when aborted.

number

Total operation budget in milliseconds. There is no default timeout.

`fs.exists()`

Check whether a remote file, directory, or other filesystem object exists.

Example

const devbox = await client.devboxes.get("sdk-example");
if (await devbox.fs.exists("/workspace/package.json")) console.log("found");

API reference

exists(remotePath: string, options?: OperationOptions): Promise<boolean>

Arguments and options

string

required

The remote path to check.

OperationOptions

Optional signal and timeoutMs operation controls.

Return value

false only when the SFTP server reports that the path does not exist. Other failures reject the promise.

`fs.rename()`

Rename or move a file or directory within the Devbox.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.fs.rename("/workspace/draft.txt", "/workspace/final.txt");

API reference

rename(oldPath: string, newPath: string, options?: OperationOptions): Promise<void>

Arguments and options

string

required

The existing remote path.

string

required

The new remote path.

OperationOptions

Optional signal and timeoutMs operation controls.

`fs.mkdir()`

Create a remote directory, optionally creating each missing parent directory.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.fs.mkdir("/workspace/output/assets", {
  recursive: true,
  mode: 0o755,
});

API reference

mkdir(remotePath: string, options?: MkdirOptions): Promise<void>

Arguments and options

string

required

The directory to create.

MkdirOptions

Hide properties

boolean

default:"false"

Creates missing parents and accepts directories that already exist.

number

POSIX permissions applied to directories created by this call. When omitted, server defaults apply.

AbortSignal

Cancels the operation when aborted.

number

Total operation budget in milliseconds. There is no default timeout.

`fs.remove()`

Remove a remote file or directory. Without recursion, directories must be empty.

Example

const devbox = await client.devboxes.get("sdk-example");
await devbox.fs.remove("/workspace/output", { recursive: true });

API reference

remove(remotePath: string, options?: RemoveOptions): Promise<void>

Arguments and options

string

required

The remote path to remove.

RemoveOptions

Hide properties

boolean

default:"false"

Runs remote rm -rf, removing a directory tree and ignoring a missing path. When false, the SDK removes one file, symlink, or empty directory.

AbortSignal

Cancels the operation when aborted.

number

Total operation budget in milliseconds. There is no default timeout.

`fs.readdir()`

List the immediate children of a remote directory. It does not recurse and excludes . and ...

Example

const devbox = await client.devboxes.get("sdk-example");
const files = (await devbox.fs.readdir("/workspace")).filter((entry) => entry.type === "file");

API reference

readdir(remotePath: string, options?: OperationOptions): Promise<DirEntry[]>

Arguments and options

string

required

The remote directory to list.

OperationOptions

Optional signal and timeoutMs operation controls.

Return value

interface DirEntry {
  name: string;
  type: "file" | "directory" | "symlink" | "other";
}

Each entry contains its basename and detected type. Symbolic links are reported as "symlink", not as the type of their target.

Errors and cancellation

All methods reject with the abort signal’s reason, or an AbortError, when cancelled. A finite, non-negative timeoutMs covers activation, connection, and the requested operation. Expiration rejects with DevboxTimeoutError. Invalid timeout values reject with RangeError; SFTP, transport, permission, and missing-path failures otherwise surface as their underlying errors. copy() and recursive remove() reject with Error when the remote command fails. See Handle errors and timeouts for shared error handling guidance.

​fs.upload()

​Example

​API reference

​Arguments and options

​fs.download()

​Example

​API reference

​Arguments and options

​fs.copy()

​Example

​API reference

​Arguments and options

​fs.readFile()

​Example

​API reference

​Arguments and options

​Return value

​fs.writeFile()

​Example

​API reference

​Arguments and options

​fs.exists()

​Example

​API reference

​Arguments and options

​Return value

​fs.rename()

​Example

​API reference

​Arguments and options

​fs.mkdir()

​Example

​API reference

​Arguments and options

​fs.remove()

​Example

​API reference

​Arguments and options

​fs.readdir()

​Example

​API reference

​Arguments and options

​Return value

​Errors and cancellation

`fs.upload()`

Example

API reference

Arguments and options

`fs.download()`

Example

API reference

Arguments and options

`fs.copy()`

Example

API reference

Arguments and options

`fs.readFile()`

Example

API reference

Arguments and options

Return value

`fs.writeFile()`

Example

API reference

Arguments and options

`fs.exists()`

Example

API reference

Arguments and options

Return value

`fs.rename()`

Example

API reference

Arguments and options

`fs.mkdir()`

Example

API reference

Arguments and options

`fs.remove()`

Example

API reference

Arguments and options

`fs.readdir()`

Example

API reference

Arguments and options

Return value

Errors and cancellation