Skip to main content

​
FileType

Sandbox filesystem object type.

​
Enumeration Members

Enumeration MemberValueDescription
DIR"dir"Filesystem object is a directory.
FILE"file"Filesystem object is a file.

​
Classes

​
Filesystem

Module for interacting with the sandbox filesystem.

​
Constructors

new Filesystem(
   transport: Transport, 
   envdApi: EnvdApiClient, 
   connectionConfig: ConnectionConfig): Filesystem
Parameters
ParameterType
transportTransport
envdApiEnvdApiClient
connectionConfigConnectionConfig
Returns
Filesystem

​
Methods

​
exists()

exists(path: string, opts?: FilesystemRequestOpts): Promise<boolean>
Check if a file or a directory exists.
Parameters
ParameterTypeDescription
pathstringpath to a file or a directory
opts?FilesystemRequestOptsconnection options.
Returns
Promise<boolean> true if the file or directory exists, false otherwise

​
getInfo()

getInfo(path: string, opts?: FilesystemRequestOpts): Promise<EntryInfo>
Get information about a file or directory.
Parameters
ParameterTypeDescription
pathstringpath to a file or directory.
opts?FilesystemRequestOptsconnection options.
Returns
Promise<EntryInfo> information about the file or directory like name, type, and path.

​
list()

list(path: string, opts?: FilesystemListOpts): Promise<EntryInfo[]>
List entries in a directory.
Parameters
ParameterTypeDescription
pathstringpath to the directory.
opts?FilesystemListOptsconnection options.
Returns
Promise<EntryInfo[]> list of entries in the sandbox filesystem directory.

​
makeDir()

makeDir(path: string, opts?: FilesystemRequestOpts): Promise<boolean>
Create a new directory and all directories along the way if needed on the specified path.
Parameters
ParameterTypeDescription
pathstringpath to a new directory. For example ‘/dirA/dirB’ when creating ‘dirB’.
opts?FilesystemRequestOptsconnection options.
Returns
Promise<boolean> true if the directory was created, false if it already exists.

​
read()

Call Signature
read(path: string, opts?: FilesystemReadOpts & object): Promise<string>
Read file content as a string. You can pass text, bytes, blob, or stream to opts.format to change the return type.
Parameters
ParameterTypeDescription
pathstringpath to the file.
opts?FilesystemReadOpts & objectconnection options.
Returns
Promise<string> file content as string
Call Signature
read(path: string, opts?: FilesystemReadOpts & object): Promise<Uint8Array<ArrayBufferLike>>
Read file content as a Uint8Array. You can pass text, bytes, blob, or stream to opts.format to change the return type.
Parameters
ParameterTypeDescription
pathstringpath to the file.
opts?FilesystemReadOpts & objectconnection options.
Returns
Promise<Uint8Array<ArrayBufferLike>> file content as Uint8Array
Call Signature
read(path: string, opts?: FilesystemReadOpts & object): Promise<Blob>
Read file content as a Blob. You can pass text, bytes, blob, or stream to opts.format to change the return type.
Parameters
ParameterTypeDescription
pathstringpath to the file.
opts?FilesystemReadOpts & objectconnection options.
Returns
Promise<Blob> file content as Blob
Call Signature
read(path: string, opts?: FilesystemReadOpts & object): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>
Read file content as a ReadableStream. You can pass text, bytes, blob, or stream to opts.format to change the return type. The request timeout bounds only the initial handshake. The returned stream holds a pooled connection until it is fully read, cancelled, errors, or the idle timeout (opts.streamIdleTimeoutMs) fires—so consume it to the end or cancel it (opts.signal).
Parameters
ParameterTypeDescription
pathstringpath to the file.
opts?FilesystemReadOpts & objectconnection options.
Returns
Promise<ReadableStream<Uint8Array<ArrayBufferLike>>> file content as ReadableStream

​
remove()

remove(path: string, opts?: FilesystemRequestOpts): Promise<void>
Remove a file or directory.
Parameters
ParameterTypeDescription
pathstringpath to a file or directory.
opts?FilesystemRequestOptsconnection options.
Returns
Promise<void>

​
rename()

rename(
   oldPath: string, 
   newPath: string, 
opts?: FilesystemRequestOpts): Promise<EntryInfo>
Rename a file or directory.
Parameters
ParameterTypeDescription
oldPathstringpath to the file or directory to rename.
newPathstringnew path for the file or directory.
opts?FilesystemRequestOptsconnection options.
Returns
Promise<EntryInfo> information about renamed file or directory.

​
watchDir()

watchDir(
   path: string, 
   onEvent: (event: FilesystemEvent) => void | Promise<void>, 
opts?: WatchOpts & object): Promise<WatchHandle>
Start watching a directory for filesystem events.
Parameters
ParameterTypeDescription
pathstringpath to directory to watch.
onEvent(event: FilesystemEvent) => void | Promise<void>callback to call when an event in the directory occurs.
opts?WatchOpts & objectconnection options.
Returns
Promise<WatchHandle> WatchHandle object for stopping watching directory.

​
write()

Call Signature
write(
   path: string, 
   data: string | ArrayBuffer | Blob | ReadableStream<any>, 
opts?: FilesystemWriteOpts): Promise<WriteInfo>
Write content to a file. Writing to a file that doesn’t exist creates the file. Writing to a file that already exists overwrites the file. Writing to a file at path that doesn’t exist creates the necessary directories.
Parameters
ParameterTypeDescription
pathstringpath to file.
datastring | ArrayBuffer | Blob | ReadableStream<any>data to write to the file. Data can be a string, ArrayBuffer, Blob, or ReadableStream.
opts?FilesystemWriteOptsconnection options.
Returns
Promise<WriteInfo> information about the written file
Call Signature
write(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>
Write content to a file. Writing to a file that doesn’t exist creates the file. Writing to a file that already exists overwrites the file. Writing to a file at path that doesn’t exist creates the necessary directories.
Parameters
ParameterTypeDescription
filesWriteEntry[]-
opts?FilesystemWriteOptsconnection options.
Returns
Promise<WriteInfo[]> information about the written file

​
writeFiles()

writeFiles(files: WriteEntry[], opts?: FilesystemWriteOpts): Promise<WriteInfo[]>
Write multiple files. Writing to a file that doesn’t exist creates the file. Writing to a file that already exists overwrites the file. Writing to a file at path that doesn’t exist creates the necessary directories.
Parameters
ParameterTypeDescription
filesWriteEntry[]list of files to write as WriteEntry objects, each containing path and data.
opts?FilesystemWriteOptsconnection options.
Returns
Promise<WriteInfo[]> information about the written files

​
Interfaces

​
EntryInfo

Sandbox filesystem object information.

​
Properties

​
group

group: string;
Group owner of the filesystem object.

​
metadata?

optional metadata: Record<string, string>;
User-defined metadata stored on the file as user.e2b.* extended attributes. On writes this reflects the metadata supplied on upload; on reads (getInfo, list, rename) it reflects any user.e2b.* xattr on the file, including ones set out-of-band. undefined when none is set.

​
mode

mode: number;
File mode and permission bits.

​
modifiedTime?

optional modifiedTime: Date;
Last modification time of the filesystem object.

​
name

name: string;
Name of the filesystem object.

​
owner

owner: string;
Owner of the filesystem object.

​
path

path: string;
Path to the filesystem object.

​
permissions

permissions: string;
String representation of file permissions (e.g. ‘rwxr-xr-x’).

​
size

size: number;
Size of the filesystem object in bytes.

​
symlinkTarget?

optional symlinkTarget: string;
If the filesystem object is a symlink, this is the target of the symlink.

​
type?

optional type: FileType;
Type of the filesystem object.

​
FilesystemListOpts

Options for the sandbox filesystem operations.

​
Properties

​
depth?

optional depth: number;
Depth of the directory to list.

​
requestTimeoutMs?

optional requestTimeoutMs: number;
Timeout for requests to the API in milliseconds.
Default
60_000 // 60 seconds

​
signal?

optional signal: AbortSignal;
An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

​
user?

optional user: string;
User to use for the operation in the sandbox. This affects the resolution of relative paths and ownership of the created filesystem objects.

​
FilesystemReadOpts

Options for reading files from the sandbox filesystem.

​
Properties

​
gzip?

optional gzip: boolean;
When true, the download will request gzip-encoded responses.

​
requestTimeoutMs?

optional requestTimeoutMs: number;
Timeout for requests to the API in milliseconds.
Default
60_000 // 60 seconds

​
signal?

optional signal: AbortSignal;
An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

​
streamIdleTimeoutMs?

optional streamIdleTimeoutMs: number;
Idle timeout for a streamed read (format: 'stream') in milliseconds: abort if no chunk arrives from the server within this window while reading. It bounds only the wire — a slow or paused consumer never trips it (a consumer that holds the stream but stops reading is reclaimed server-side). Defaults to the request timeout (60s); pass 0 to disable.

​
user?

optional user: string;
User to use for the operation in the sandbox. This affects the resolution of relative paths and ownership of the created filesystem objects.

​
FilesystemRequestOpts

Options for the sandbox filesystem operations.

​
Extended by

  • FilesystemWriteOpts
  • FilesystemReadOpts
  • FilesystemListOpts
  • WatchOpts

​
Properties

​
requestTimeoutMs?

optional requestTimeoutMs: number;
Timeout for requests to the API in milliseconds.
Default
60_000 // 60 seconds

​
signal?

optional signal: AbortSignal;
An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

​
user?

optional user: string;
User to use for the operation in the sandbox. This affects the resolution of relative paths and ownership of the created filesystem objects.

​
FilesystemWriteOpts

Options for writing files to the sandbox filesystem.

​
Properties

​
gzip?

optional gzip: boolean;
When true, the upload will be gzip-compressed. Implies the application/octet-stream upload. Requires envd 0.5.7 or later — when not supported by the sandbox’s envd version, the upload falls back to uncompressed multipart/form-data.

​
metadata?

optional metadata: Record<string, string>;
User-defined metadata to persist on the uploaded file(s) as extended attributes. Keys are lowercased by the sandbox, so they may differ in case when read back. Invalid keys or values throw an InvalidArgumentError. The same metadata is applied to every file in a multi-file upload. Requires envd 0.6.2 or later.

​
requestTimeoutMs?

optional requestTimeoutMs: number;
Timeout for requests to the API in milliseconds.
Default
60_000 // 60 seconds

​
signal?

optional signal: AbortSignal;
An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

​
useOctetStream?

optional useOctetStream: boolean;
When true, the upload uses application/octet-stream instead of multipart/form-data. Outside the browser, ReadableStream data is then streamed to the sandbox instead of being buffered in memory. Defaults to undefined, which uses octet-stream when any entry is a ReadableStream (so streamed uploads aren’t buffered) and multipart/form-data otherwise; browsers always use multipart/form-data since they can’t stream request bodies. Requires envd 0.5.7 or later — when not supported by the sandbox’s envd version, the upload falls back to multipart/form-data.

​
user?

optional user: string;
User to use for the operation in the sandbox. This affects the resolution of relative paths and ownership of the created filesystem objects.

​
WatchOpts

Options for watching a directory.

​
Properties

​
allowNetworkMounts?

optional allowNetworkMounts: boolean;
Allow watching paths on network filesystem mounts (NFS, CIFS, SMB, FUSE), which are rejected by default. Events on network mounts may be unreliable or not delivered at all. Requires envd 0.6.4 or later. Watching with this option against an older sandbox throws a TemplateError.

​
includeEntry?

optional includeEntry: boolean;
Include the EntryInfo of the affected entry in each FilesystemEvent. The entry is populated best-effort and may be undefined for events where the entry no longer exists at the path (e.g. remove or rename-away events). Requires envd 0.6.3 or later. Watching with this option against an older sandbox throws a TemplateError.

​
onExit()?

optional onExit: (err?: Error) => void | Promise<void>;
Callback to call when the watch operation stops.
Parameters
ParameterType
err?Error
Returns
void | Promise<void>

​
recursive?

optional recursive: boolean;
Watch the directory recursively

​
requestTimeoutMs?

optional requestTimeoutMs: number;
Timeout for requests to the API in milliseconds.
Default
60_000 // 60 seconds

​
signal?

optional signal: AbortSignal;
An optional AbortSignal that can be used to cancel the in-flight request. When the signal is aborted, the underlying fetch is aborted and the returned promise rejects with an AbortError.

​
timeoutMs?

optional timeoutMs: number;
Timeout for the watch operation in milliseconds. You can pass 0 to disable the timeout.
Default
60_000 // 60 seconds

​
user?

optional user: string;
User to use for the operation in the sandbox. This affects the resolution of relative paths and ownership of the created filesystem objects.

​
WriteInfo

Sandbox filesystem object information.

​
Extended by

  • EntryInfo

​
Properties

​
metadata?

optional metadata: Record<string, string>;
User-defined metadata stored on the file as user.e2b.* extended attributes. On writes this reflects the metadata supplied on upload; on reads (getInfo, list, rename) it reflects any user.e2b.* xattr on the file, including ones set out-of-band. undefined when none is set.

​
name

name: string;
Name of the filesystem object.

​
path

path: string;
Path to the filesystem object.

​
type?

optional type: FileType;
Type of the filesystem object.

​
Type Aliases

​
WriteEntry

type WriteEntry = object;

​
Type declaration

NameType
datastring | ArrayBuffer | Blob | ReadableStream
pathstring

​
Functions

​
mapEntryInfo()

function mapEntryInfo(entry: EntryInfo): EntryInfo
Map a protobuf EntryInfo to the SDK EntryInfo.

​
Parameters

ParameterType
entryEntryInfo

​
Returns

EntryInfo