File System Operations

Upload, download, and manage files in Daytona sandboxes

The File System API provides comprehensive file management capabilities for working with files and directories within sandbox environments.

Overview

Daytona’s file system operations support:

• File upload/download - Transfer files between local system and sandbox
• Directory management - Create, list, and navigate directories
• File search - Search by name patterns or content
• Batch operations - Process multiple files efficiently

File Upload

Upload from Buffer

Upload file content directly from memory:

const configData = JSON.stringify({
  name: 'my-config',
  version: '1.0.0'
}, null, 2);

await sandbox.fs.uploadFile(
  Buffer.from(configData),
  'config.json'
);

Upload from Local File

Upload a file from your local filesystem:

await sandbox.fs.uploadFile(
  'local/path/to/file.txt',
  '/workspace/remote/file.txt'
);

Upload Multiple Files

Efficiently upload multiple files in a single operation:

await sandbox.fs.uploadFiles([
  {
    source: 'local-file.txt',
    destination: '/workspace/file1.txt'
  },
  {
    source: Buffer.from('Content'),
    destination: '/workspace/file2.txt'
  },
  {
    source: Buffer.from('#!/bin/bash\necho "Hello"'),
    destination: '/workspace/script.sh'
  }
]);

files · FileUpload[] · required

Array of files to upload

Show FileUpload properties

source · string | Buffer · required

File to upload. String path for local file (streamed), or Buffer for in-memory content.

destination · string · required

Absolute destination path in the sandbox. Relative paths resolved from sandbox working directory.

timeout · number

Upload timeout in seconds. Default is 30 minutes (1800 seconds). Set to 0 for no timeout.

File Download

Download to Buffer

Download a file into memory:

const buffer = await sandbox.fs.downloadFile('config.json');
console.log('Content:', buffer.toString());

Download to Local File

Download and save to your local filesystem:

await sandbox.fs.downloadFile(
  '/workspace/data.json',
  'local-data.json'
);

Download Multiple Files

Download multiple files efficiently:

const results = await sandbox.fs.downloadFiles([
  {
    source: 'config.json',
    destination: 'local-config.json'
  },
  {
    source: 'data.txt' // No destination = download to buffer
  }
]);

for (const result of results) {
  if (result.error) {
    console.error(`Error: ${result.error}`);
  } else if (typeof result.result === 'string') {
    console.log(`Downloaded to: ${result.result}`);
  } else {
    console.log(`Downloaded ${result.result?.length} bytes`);
  }
}

files · FileDownloadRequest[] · required

Array of download requests

Show FileDownloadRequest properties

source · string · required

Source path in sandbox. Relative paths resolved from sandbox working directory.

destination · string

Local path to save file. If omitted, file is downloaded to Buffer (may cause memory issues for large files).

timeout · number

Download timeout in seconds. Default is 30 minutes (1800 seconds).

Directory Management

Create Directory

await sandbox.fs.createFolder(
  'project/data',
  '755' // permissions in octal format
);

List Directory Contents

const files = await sandbox.fs.listFiles('/workspace');

files.forEach(file => {
  console.log(`${file.name} (${file.size} bytes)`);
  console.log(`Modified: ${file.modTime}`);
  console.log(`Is directory: ${file.isDir}`);
});

Get File Details

const info = await sandbox.fs.getFileDetails('config.json');

console.log(`Size: ${info.size}`);
console.log(`Permissions: ${info.mode}`);
console.log(`Owner: ${info.owner}:${info.group}`);
console.log(`Modified: ${info.modTime}`);

File Operations

Move or Rename Files

await sandbox.fs.moveFiles(
  'old-location/file.txt',
  'new-location/file.txt'
);

Delete Files or Directories

// Delete a file
await sandbox.fs.deleteFile('temp-file.txt');

// Delete a directory recursively
await sandbox.fs.deleteFile('temp-dir', true);

Set File Permissions

await sandbox.fs.setFilePermissions('script.sh', {
  mode: '755',    // rwxr-xr-x
  owner: 'daytona',
  group: 'users'
});

path · string · required

Path to file or directory. Relative paths resolved from sandbox working directory.

permissions · FilePermissionsParams · required

Permission settings

Show properties

mode · string

File mode in octal format (e.g., “644”, “755”)

owner · string

User owner of the file

group · string

Group owner of the file

File Search

Search by Name Pattern

Find files using glob patterns:

const result = await sandbox.fs.searchFiles(
  '/workspace',
  '*.json'
);

console.log(`Found ${result.files.length} JSON files`);
result.files.forEach(file => console.log(file));

Search by Content

Search for text patterns within files:

const matches = await sandbox.fs.findFiles(
  '/workspace',
  'TODO:'
);

matches.forEach(match => {
  console.log(`${match.file}:${match.line}`);
  console.log(match.content);
});

Text Replacement

Replace in Multiple Files

Find and replace text across multiple files:

const results = await sandbox.fs.replaceInFiles(
  ['package.json', 'version.ts'],
  '"version": "1.0.0"',
  '"version": "1.1.0"'
);

results.forEach(result => {
  console.log(`${result.file}: ${result.matches} replacements`);
});

files · string[] · required

Array of file paths. Relative paths resolved from sandbox working directory.

pattern · string · required

Text pattern to replace

newValue · string · required

Replacement text

Best Practices

Use streaming for large files

When uploading or downloading large files, provide a local file path instead of using buffers to enable streaming and avoid memory issues.

// Good: Streams the file
await sandbox.fs.uploadFile('large-file.zip', '/remote/large-file.zip');

// Bad: Loads entire file into memory
const buffer = fs.readFileSync('large-file.zip');
await sandbox.fs.uploadFile(buffer, '/remote/large-file.zip');

Batch operations for efficiency

Use batch upload/download operations when working with multiple files to reduce network overhead.

Handle errors gracefully

Check for errors in batch operations, as individual files may fail while others succeed.

const results = await sandbox.fs.downloadFiles(requests);
results.forEach(result => {
  if (result.error) {
    console.error(`Failed: ${result.source}: ${result.error}`);
  }
});

Use absolute paths

While relative paths are resolved based on the sandbox working directory, using absolute paths makes your code more explicit and prevents confusion.

Complete Example

import { Daytona } from '@daytonaio/sdk';
import * as fs from 'fs';

const daytona = new Daytona();
const sandbox = await daytona.create();

try {
  // Create directory
  await sandbox.fs.createFolder('project', '755');
  
  // Upload multiple files
  await sandbox.fs.uploadFiles([
    {
      source: 'local-file.txt',
      destination: 'project/file.txt'
    },
    {
      source: Buffer.from('{"version": "1.0.0"}'),
      destination: 'project/config.json'
    }
  ]);
  
  // Search for JSON files
  const jsonFiles = await sandbox.fs.searchFiles('project', '*.json');
  console.log('Found JSON files:', jsonFiles.files);
  
  // Update version in files
  await sandbox.fs.replaceInFiles(
    ['project/config.json'],
    '"version": "1.0.0"',
    '"version": "1.1.0"'
  );
  
  // Download updated file
  const buffer = await sandbox.fs.downloadFile('project/config.json');
  console.log('Updated config:', buffer.toString());
  
} finally {
  await daytona.delete(sandbox);
}

Related Resources

Process Execution

Execute commands and code in sandboxes

Git Operations

Clone and manage Git repositories