FileSystem

Main class for a new FileSystem instance.

Constructors

new FileSystem()

def initialize(sandbox_id:, toolbox_api:, otel_state: nil)

Initializes a new FileSystem instance.

Parameters:

• sandbox_id String - The Sandbox ID
• toolbox_api DaytonaToolboxApiClient:FileSystemApi - API client for Sandbox operations
• otel_state Daytona:OtelState, nil -

Returns:

• FileSystem - a new instance of FileSystem

Methods

sandbox_id()

def sandbox_id()

Returns:

• String - The Sandbox ID

toolbox_api()

def toolbox_api()

Returns:

• DaytonaToolboxApiClient:FileSystemApi - API client for Sandbox operations

create_folder()

def create_folder(path, mode)

Creates a new directory in the Sandbox at the specified path with the given permissions.

Parameters:

• path String - Path where the folder should be created. Relative paths are resolved based on the sandbox working directory.
• mode String - Folder permissions in octal format (e.g., "755" for rwxr-xr-x).

Returns:

• void

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Create a directory with standard permissions
sandbox.fs.create_folder("workspace/data", "755")

# Create a private directory
sandbox.fs.create_folder("workspace/secrets", "700")

delete_file()

def delete_file(path, recursive: false)

Deletes a file from the Sandbox.

Parameters:

• path String - Path to the file 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:

• void

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Delete a file
sandbox.fs.delete_file("workspace/data/old_file.txt")

# Delete a directory recursively
sandbox.fs.delete_file("workspace/old_dir", recursive: true)

get_file_info()

def get_file_info(path)

Gets detailed information about a file or directory, including its size, permissions, and timestamps.

Parameters:

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

Returns:

• DaytonaApiClient:FileInfo - Detailed file information

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Get file metadata
info = sandbox.fs.get_file_info("workspace/data/file.txt")
puts "Size: #{info.size} bytes"
puts "Modified: #{info.mod_time}"
puts "Mode: #{info.mode}"

# Check if path is a directory
info = sandbox.fs.get_file_info("workspace/data")
puts "Path is a directory" if info.is_dir

list_files()

def list_files(path, depth: nil)

Lists files and directories in a given path and returns their information, similar to the ls -l command.

Parameters:

• path String - Path to the directory to list contents from. Relative paths are resolved based on the sandbox working directory.
• depth Integer, nil - How many levels deep to list. depth=1 (default) lists the directory's entries, depth=2 also includes their children, and so on. Must be >= 1. Each returned FileInfo carries a full path field.

Returns:

• Array\<DaytonaApiClient:FileInfo\> - List of file and directory information

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# List directory contents
files = sandbox.fs.list_files("workspace/data")

# Print files and their sizes
files.each do |file|
  puts "#{file.name}: #{file.size} bytes" unless file.is_dir
end

# List only directories
dirs = files.select(&:is_dir)
puts "Subdirectories: #{dirs.map(&:name).join(', ')}"

download_file()

def download_file(remote_path, local_path = nil)

Downloads a file from the Sandbox. Returns the file contents as a string. This method is useful when you want to load the file into memory without saving it to disk. It can only be used for smaller files.

Parameters:

• remote_path String - Path to the file in the Sandbox. Relative paths are resolved based on the sandbox working directory.
• local_path String, nil - Optional path to save the file locally. If provided, the file will be saved to disk.

Returns:

• File, nil - The file if local_path is nil, otherwise nil

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Download and get file content
content = sandbox.fs.download_file("workspace/data/file.txt")
puts content

# Download and save a file locally
sandbox.fs.download_file("workspace/data/file.txt", "local_copy.txt")
size_mb = File.size("local_copy.txt") / 1024.0 / 1024.0
puts "Size of the downloaded file: #{size_mb} MB"

download_file_stream()

def download_file_stream(remote_path, timeout: 30 * 60, on_progress: nil, cancel_event: nil)

Downloads a single file from the Sandbox as a stream without buffering the entire file into memory. Yields file content in chunks to the given block, or returns an Enumerator if no block is given.

Parameters:

• remote_path String - Path to the file in the Sandbox. Relative paths are resolved based on the sandbox working directory.
• timeout Integer - Timeout for the download operation in seconds. 0 means no timeout. Default is 30 minutes.
• on_progress Proc, nil - Optional callback invoked with a Daytona::DownloadProgress struct containing bytes_received (Integer) and total_bytes (Integer or nil).
• cancel_event #set?, nil - Optional cancellation token (anything responding to +set?+; the standard library's +Concurrent::Event+ or a small ad-hoc object both work). When set during streaming, the next chunk raises Daytona::Sdk::Error and the underlying HTTP connection is torn down.

Returns:

• Enumerator, nil - An Enumerator yielding chunks if no block given, nil otherwise

Raises:

• Daytona:Sdk:Error - If the file does not exist, the operation fails, or +cancel_event+ is set during streaming

Examples:

File.open("local_copy.bin", "wb") do |f|
  sandbox.fs.download_file_stream("workspace/large-file.bin") { |chunk| f.write(chunk) }
end

content = sandbox.fs.download_file_stream("workspace/data.json").reduce(:+)
puts content

upload_file()

def upload_file(source, remote_path)

Uploads a file to the specified path in the Sandbox. If a file already exists at the destination path, it will be overwritten.

Parameters:

• source String, IO - File contents as a string/bytes or a local file path or IO object.
• remote_path String - Path to the destination file. Relative paths are resolved based on the sandbox working directory.

Returns:

• void

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Upload a text file from string content
content = "Hello, World!"
sandbox.fs.upload_file(content, "tmp/hello.txt")

# Upload a local file
sandbox.fs.upload_file("local_file.txt", "tmp/file.txt")

# Upload binary data
data = { key: "value" }.to_json
sandbox.fs.upload_file(data, "tmp/config.json")

upload_file_stream()

def upload_file_stream(source, remote_path, timeout: 30 * 60, on_progress: nil, cancel_event: nil)

Streams +source+ to the Sandbox without buffering its contents in memory, with optional progress reporting.

Parameters:

• source String, IO - A local file path or any IO-like object responding to +read(n)+. Strings that don't reference an existing file are uploaded as their raw bytes (still streamed, just from memory).
• remote_path String - Destination path in the Sandbox.
• timeout Integer - Timeout in seconds. 0 means no timeout. Default 30 minutes.
• on_progress Proc, nil - Optional callback invoked with a +Daytona::UploadProgress+ struct as libcurl reports bytes actually uploaded.
• cancel_event #set?, nil - Optional cancellation token. When set while staging a non-file source or during the libcurl upload, the operation raises Daytona::Sdk::Error and the in-progress upload is aborted (no destination file is left on the sandbox thanks to the daemon's atomic-rename behaviour).

Returns:

• void

Raises:

• Daytona:Sdk:Error - If the operation fails or +cancel_event+ is set.

Examples:

File.open("large.bin", "rb") do |f|
  sandbox.fs.upload_file_stream(f, "tmp/large.bin",
    on_progress: ->(p) { puts "#{p.bytes_sent} bytes sent" })
end

upload_files()

def upload_files(files)

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

Parameters:

• files Array<FileUpload> - List of files to upload.

Returns:

• void

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Upload multiple files
files = [
  FileUpload.new("Content of file 1", "/tmp/file1.txt"),
  FileUpload.new("workspace/data/file2.txt", "/tmp/file2.txt"),
  FileUpload.new('{"key": "value"}', "/tmp/config.json")
]
sandbox.fs.upload_files(files)

find_files()

def find_files(path, pattern)

Searches for files containing a pattern, similar to the grep command.

Parameters:

• path String - Path to the file or directory to search. If the path is a directory, the search will be performed recursively. Relative paths are resolved based on the sandbox working directory.
• pattern String - Search pattern to match against file contents.

Returns:

• Array\<DaytonaApiClient:Match\> - List of matches found in files

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Search for TODOs in Ruby files
matches = sandbox.fs.find_files("workspace/src", "TODO:")
matches.each do |match|
  puts "#{match.file}:#{match.line}: #{match.content.strip}"
end

search_files()

def search_files(path, pattern)

Searches for files and directories whose names match the specified pattern. The pattern can be a simple string or a glob pattern.

Parameters:

• path String - Path to the root directory to start search from. Relative paths are resolved based on the sandbox working directory.
• pattern String - Pattern to match against file names. Supports glob patterns (e.g., "*.rb" for Ruby files).

Returns:

• DaytonaApiClient:SearchFilesResponse

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Find all Ruby files
result = sandbox.fs.search_files("workspace", "*.rb")
result.files.each { |file| puts file }

# Find files with specific prefix
result = sandbox.fs.search_files("workspace/data", "test_*")
puts "Found #{result.files.length} test files"

move_files()

def move_files(source, destination)

Moves or renames a file or directory. The parent directory of the destination must exist.

Parameters:

• source String - Path to the source file or directory. Relative paths are resolved based on the sandbox working directory.
• destination String - Path to the destination. Relative paths are resolved based on the sandbox working directory.

Returns:

• void

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Rename a file
sandbox.fs.move_files(
  "workspace/data/old_name.txt",
  "workspace/data/new_name.txt"
)

# Move a file to a different directory
sandbox.fs.move_files(
  "workspace/data/file.txt",
  "workspace/archive/file.txt"
)

# Move a directory
sandbox.fs.move_files(
  "workspace/old_dir",
  "workspace/new_dir"
)

replace_in_files()

def replace_in_files(files:, pattern:, new_value:)

Performs search and replace operations across multiple files.

Parameters:

• files Array<String> - List of file paths to perform replacements in. Relative paths are resolved based on the sandbox working directory.
• pattern String - Pattern to search for.
• new_value String - Text to replace matches with.

Returns:

• Array\<DaytonaApiClient:ReplaceResult\> - List of results indicating replacements made in each file

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Replace in specific files
results = sandbox.fs.replace_in_files(
  files: ["workspace/src/file1.rb", "workspace/src/file2.rb"],
  pattern: "old_function",
  new_value: "new_function"
)

# Print results
results.each do |result|
  if result.success
    puts "#{result.file}: #{result.success}"
  else
    puts "#{result.file}: #{result.error}"
  end
end

set_file_permissions()

def set_file_permissions(path:, mode: nil, owner: nil, group: nil)

Sets permissions and ownership for a file or directory. Any of the parameters can be nil to leave that attribute unchanged.

Parameters:

• path String - Path to the file or directory. Relative paths are resolved based on the sandbox working directory.
• mode String, nil - File mode/permissions in octal format (e.g., "644" for rw-r--r--).
• owner String, nil - User owner of the file.
• group String, nil - Group owner of the file.

Returns:

• void

Raises:

• Daytona:Sdk:Error - If the operation fails

Examples:

# Make a file executable
sandbox.fs.set_file_permissions(
  path: "workspace/scripts/run.sh",
  mode: "755"  # rwxr-xr-x
)

# Change file owner
sandbox.fs.set_file_permissions(
  path: "workspace/data/file.txt",
  owner: "daytona",
  group: "daytona"
)