Skip to content
View as Markdown

FileSystem

Provides file system operations within a Sandbox.

Constructors

new FileSystem()

new FileSystem(
   clientConfig: Configuration,
   apiClient: FileSystemApi,
   ensureToolboxUrl: () => Promise<void>): FileSystem

Parameters:

  • clientConfig Configuration
  • apiClient FileSystemApi
  • ensureToolboxUrl () => Promise<void>

Returns:

  • FileSystem

Methods

createFolder()

createFolder(path: string, mode: string): Promise<void>

Create a new directory in the Sandbox with specified permissions.

Parameters:

  • path string - Path where the directory should be created. Relative paths are resolved based on the sandbox working directory.
  • mode string - Directory permissions in octal format (e.g. “755”)

Returns:

  • Promise<void>

Example:

// Create a directory with standard permissions
await fs.createFolder('app/data', '755');

deleteFile()

deleteFile(path: string, recursive?: boolean): Promise<void>

Deletes a file or directory from the Sandbox.

Parameters:

  • path string - Path to the file or directory to delete. Relative paths are resolved based on the sandbox working directory.
  • recursive? boolean - If the file is a directory, this must be true to delete it.

Returns:

  • Promise<void>

Example:

// Delete a file
await fs.deleteFile('app/temp.log');

downloadFile()

Call Signature
downloadFile(remotePath: string, timeout?: number): Promise<Buffer<ArrayBufferLike>>

Downloads a file from the Sandbox. This method loads the entire file into memory, so it is not recommended for downloading large files.

Parameters:

  • remotePath string - Path to the file to download. Relative paths are resolved based on the sandbox working directory.
  • timeout? number - Timeout for the download operation in seconds. 0 means no timeout. Default is 30 minutes.

Returns:

  • Promise<Buffer<ArrayBufferLike>> - The file contents as a Buffer.

Example:

// Download and process a file
const fileBuffer = await fs.downloadFile('tmp/data.json');
console.log('File content:', fileBuffer.toString());
Call Signature
downloadFile(
   remotePath: string,
   localPath: string,
timeout?: number): Promise<void>

Downloads a file from the Sandbox and saves it to a local file. This method uses streaming to download the file, so it is recommended for downloading larger files.

Parameters:

  • remotePath string - Path to the file to download in the Sandbox. Relative paths are resolved based on the sandbox working directory.
  • localPath string - Path to save the downloaded file.
  • timeout? number - Timeout for the download operation in seconds. 0 means no timeout. Default is 30 minutes.

Returns:

  • Promise<void>

Example:

// Download and save a file
await fs.downloadFile('tmp/data.json', 'local_file.json');

downloadFiles()

downloadFiles(files: FileDownloadRequest[], timeoutSec?: number): Promise<FileDownloadResponse[]>

Downloads multiple files from the Sandbox. If the files already exist locally, they will be overwritten.

Parameters:

  • files FileDownloadRequest[] - Array of file download requests.
  • timeoutSec? number = … - Timeout for the download operation in seconds. 0 means no timeout. Default is 30 minutes.

Returns:

  • Promise<FileDownloadResponse[]> - Array of download results.

Throws:

If the request itself fails (network issues, invalid request/response, etc.). Individual file download errors are returned in the FileDownloadResponse.error field.

Example:

// Download multiple files
const results = await fs.downloadFiles([
  { source: 'tmp/data.json' },
  { source: 'tmp/config.json', destination: 'local_config.json' }
]);
results.forEach(result => {
  if (result.error) {
    console.error(`Error downloading ${result.source}: ${result.error}`);
  } else if (result.result) {
    console.log(`Downloaded ${result.source} to ${result.result}`);
  }
});

findFiles()

findFiles(path: string, pattern: string): Promise<Match[]>

Searches for text patterns within files in the Sandbox.

Parameters:

  • path string - Directory to search in. Relative paths are resolved based on the sandbox working directory.
  • pattern string - Search pattern

Returns:

  • Promise<Match[]> - Array of matches with file and line information

Example:

// Find all TODO comments in TypeScript files
const matches = await fs.findFiles('app/src', 'TODO:');
matches.forEach(match => {
  console.log(`${match.file}:${match.line}: ${match.content}`);
});

getFileDetails()

getFileDetails(path: string): Promise<FileInfo>

Retrieves detailed information about a file or directory.

Parameters:

  • path string - Path to the file or directory. Relative paths are resolved based on the sandbox working directory.

Returns:

  • Promise<FileInfo> - Detailed file information including size, permissions, modification time

Example:

// Get file details
const info = await fs.getFileDetails('app/config.json');
console.log(`Size: ${info.size}, Modified: ${info.modTime}`);

listFiles()

listFiles(path: string): Promise<FileInfo[]>

Lists contents of a directory in the Sandbox.

Parameters:

  • path string - Directory path to list. Relative paths are resolved based on the sandbox working directory.

Returns:

  • Promise<FileInfo[]> - Array of file and directory information

Example:

// List directory contents
const files = await fs.listFiles('app/src');
files.forEach(file => {
  console.log(`${file.name} (${file.size} bytes)`);
});

moveFiles()

moveFiles(source: string, destination: string): Promise<void>

Moves or renames a file or directory.

Parameters:

  • source string - Source path. Relative paths are resolved based on the sandbox working directory.
  • destination string - Destination path. Relative paths are resolved based on the sandbox working directory.

Returns:

  • Promise<void>

Example:

// Move a file to a new location
await fs.moveFiles('app/temp/data.json', 'app/data/data.json');

replaceInFiles()

replaceInFiles(
   files: string[],
   pattern: string,
newValue: string): Promise<ReplaceResult[]>

Replaces text content in multiple files.

Parameters:

  • files string[] - Array of file paths to process. Relative paths are resolved based on the sandbox working directory.
  • pattern string - Pattern to replace
  • newValue string - Replacement text

Returns:

  • Promise<ReplaceResult[]> - Results of the replace operation for each file

Example:

// Update version number across multiple files
const results = await fs.replaceInFiles(
  ['app/package.json', 'app/version.ts'],
  '"version": "1.0.0"',
  '"version": "1.1.0"'
);

searchFiles()

searchFiles(path: string, pattern: string): Promise<SearchFilesResponse>

Searches for files and directories by name pattern in the Sandbox.

Parameters:

  • path string - Directory to search in. Relative paths are resolved based on the sandbox working directory.
  • pattern string - File name pattern (supports globs)

Returns:

  • Promise<SearchFilesResponse> - Search results with matching files

Example:

// Find all TypeScript files
const result = await fs.searchFiles('app', '*.ts');
result.files.forEach(file => console.log(file));

setFilePermissions()

setFilePermissions(path: string, permissions: FilePermissionsParams): Promise<void>

Sets permissions and ownership for a file or directory.

Parameters:

  • path string - Path to the file or directory. Relative paths are resolved based on the sandbox working directory.
  • permissions FilePermissionsParams - Permission settings

Returns:

  • Promise<void>

Example:

// Set file permissions and ownership
await fs.setFilePermissions('app/script.sh', {
  owner: 'daytona',
  group: 'users',
  mode: '755'  // Execute permission for shell script
});

uploadFile()

Call Signature
uploadFile(
   file: Buffer,
   remotePath: string,
timeout?: number): Promise<void>

Uploads a file to the Sandbox. This method loads the entire file into memory, so it is not recommended for uploading large files.

Parameters:

  • file Buffer - Buffer of the file to upload.
  • remotePath string - Destination path in the Sandbox. Relative paths are resolved based on the sandbox working directory.
  • timeout? number - Timeout for the upload operation in seconds. 0 means no timeout. Default is 30 minutes.

Returns:

  • Promise<void>

Example:

// Upload a configuration file
await fs.uploadFile(Buffer.from('{"setting": "value"}'), 'tmp/config.json');
Call Signature
uploadFile(
   localPath: string,
   remotePath: string,
timeout?: number): Promise<void>

Uploads a file from the local file system to the Sandbox. This method uses streaming to upload the file, so it is recommended for uploading larger files.

Parameters:

  • localPath string - Path to the local file to upload.
  • remotePath string - Destination path in the Sandbox. Relative paths are resolved based on the sandbox working directory.
  • timeout? number - Timeout for the upload operation in seconds. 0 means no timeout. Default is 30 minutes.

Returns:

  • Promise<void>

Example:

// Upload a local file
await fs.uploadFile('local_file.txt', 'tmp/file.txt');

uploadFiles()

uploadFiles(files: FileUpload[], timeout?: number): Promise<void>

Uploads multiple files to the Sandbox. If files already exist at the destination paths, they will be overwritten.

Parameters:

  • files FileUpload[] - Array of files to upload.
  • timeout? number = … - Timeout for the upload operation in seconds. 0 means no timeout. Default is 30 minutes.

Returns:

  • Promise<void>

Example:

// Upload multiple text files
const files = [
  {
    source: Buffer.from('Content of file 1'),
    destination: '/tmp/file1.txt'
  },
  {
    source: 'app/data/file2.txt',
    destination: '/tmp/file2.txt'
  },
  {
    source: Buffer.from('{"key": "value"}'),
    destination: '/tmp/config.json'
  }
];
await fs.uploadFiles(files);

DownloadMetadata

Represents metadata for a file download operation.

Properties:

  • destination? string - Destination path in the local filesystem where the file content will be streamed to.
  • error? string - Error message if the download failed, undefined if successful.
  • result? string | Uint8Array<ArrayBufferLike> | Buffer<ArrayBufferLike> - The download result - file path (if destination provided in the request) or bytes content (if no destination in the request), undefined if failed or no data received.

FileDownloadRequest

Represents a request to download a single file from the Sandbox.

Properties:

  • destination? string - Destination path in the local filesystem where the file content will be streamed to. If not provided, the file will be downloaded in the bytes buffer (might cause memory issues if the file is large).
  • source string - Source path in the Sandbox. Relative paths are resolved based on the user’s root directory.

FileDownloadResponse

Represents the response to a single file download request.

Properties:

  • error? string - Error message if the download failed, undefined if successful.
  • result? string | Buffer<ArrayBufferLike> - The download result - file path (if destination provided in the request) or bytes content (if no destination in the request), undefined if failed or no data received.
  • source string - The original source path requested for download.

FilePermissionsParams

Parameters for setting file permissions in the Sandbox.

Properties:

  • group? string - Group owner of the file
  • mode? string - File mode/permissions in octal format (e.g. “644”)
  • owner? string - User owner of the file

Example:

const permissions: FilePermissionsParams = {
  mode: '644',
  owner: 'daytona',
  group: 'users'
};

FileUpload

Represents a file to be uploaded to the Sandbox.

Properties:

  • destination string - Absolute destination path in the Sandbox. Relative paths are resolved based on the sandbox working directory.
  • source string | Buffer<ArrayBufferLike> - File to upload. If a Buffer, it is interpreted as the file content which is loaded into memory. Make sure it fits into memory, otherwise use the local file path which content will be streamed to the Sandbox.