daytona-sdk 0.125.0

data/lib/daytona/daytona.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module Daytona
+  class Daytona # rubocop:disable Metrics/ClassLength
+    # @return [Daytona::Config]
+    attr_reader :config
+
+    # @return [DaytonaApiClient]
+    attr_reader :api_client
+
+    # @return [DaytonaApiClient::SandboxApi]
+    attr_reader :sandbox_api
+
+    # @return [DaytonaApiClient::ToolboxApi]
+    attr_reader :toolbox_api
+
+    # @return [Daytona::VolumeService]
+    attr_reader :volume
+
+    # @return [DaytonaApiClient::ObjectStorageApi]
+    attr_reader :object_storage_api
+
+    # @return [DaytonaApiClient::SnapshotsApi]
+    attr_reader :snapshots_api
+
+    # @return [Daytona::SnapshotService]
+    attr_reader :snapshot
+
+    # @param config [Daytona::Config] Configuration options. Defaults to Daytona::Config.new
+    def initialize(config = Config.new) # rubocop:disable Metrics/AbcSize
+      @config = config
+      ensure_access_token_defined
+      @api_client = build_api_client
+      @sandbox_api = DaytonaApiClient::SandboxApi.new(api_client)
+      @toolbox_api = DaytonaApiClient::ToolboxApi.new(api_client)
+      @volume = VolumeService.new(DaytonaApiClient::VolumesApi.new(api_client))
+      @object_storage_api = DaytonaApiClient::ObjectStorageApi.new(api_client)
+      @snapshots_api = DaytonaApiClient::SnapshotsApi.new(api_client)
+      @snapshot = SnapshotService.new(snapshots_api:, object_storage_api:)
+    end
+
+    # Creates a sandbox with the specified parameters
+    #
+    # @param params [Daytona::CreateSandboxFromSnapshotParams, Daytona::CreateSandboxFromImageParams, Nil] Sandbox creation parameters
+    # @return [Daytona::Sandbox] The created sandbox
+    # @raise [Daytona::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    def create(params = nil, on_snapshot_create_logs: nil)
+      if params.nil?
+        params = CreateSandboxFromSnapshotParams.new(language: CodeLanguage::PYTHON)
+      elsif params.language.nil?
+        params.language = CodeLanguage::PYTHON
+      end
+
+      _create(params, on_snapshot_create_logs:)
+    end
+
+    # Deletes a Sandbox.
+    #
+    # @param sandbox [Daytona::Sandbox]
+    # @return [void]
+    def delete(sandbox) = sandbox.delete
+
+    # Gets a Sandbox by its ID.
+    #
+    # @param id [String]
+    # @return [Daytona::Sandbox]
+    def get(id)
+      sandbox_dto = sandbox_api.get_sandbox(id)
+      to_sandbox(sandbox_dto:, code_toolbox: code_toolbox_from_labels(sandbox_dto.labels))
+    end
+
+    # Finds a Sandbox by its ID or labels.
+    #
+    # @param id [String, Nil]
+    # @param labels [Hash<String, String>]
+    # @return [Daytona::Sandbox]
+    # @raise [Daytona::Sdk::Error]
+    def find_one(id: nil, labels: nil)
+      return get(id) if id
+
+      response = list(labels)
+      raise Sdk::Error, "No sandbox found with labels #{labels}" if response.items.empty?
+
+      response.items.first
+    end
+
+    # Lists Sandboxes filtered by labels.
+    #
+    # @param labels [Hash<String, String>]
+    # @param page [Integer, Nil]
+    # @param limit [Integer, Nil]
+    # @return [Daytona::PaginatedResource]
+    # @raise [Daytona::Sdk::Error]
+    def list(labels = {}, page: nil, limit: nil) # rubocop:disable Metrics/MethodLength
+      raise Sdk::Error, 'page must be positive integer' if page && page < 1
+
+      raise Sdk::Error, 'limit must be positive integer' if limit && limit < 1
+
+      response = sandbox_api.list_sandboxes_paginated(labels: JSON.dump(labels), page:, limit:)
+
+      PaginatedResource.new(
+        total: response.total,
+        page: response.page,
+        total_pages: response.total_pages,
+        items: response
+          .items
+          .map { |sandbox_dto| to_sandbox(sandbox_dto:, code_toolbox: code_toolbox_from_labels(sandbox_dto.labels)) }
+      )
+    end
+
+    # Starts a Sandbox and waits for it to be ready.
+    #
+    # @param sandbox [Daytona::Sandbox]
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def start(sandbox, timeout = Sandbox::DEFAULT_TIMEOUT) = sandbox.start(timeout)
+
+    # Stops a Sandbox and waits for it to be stopped.
+    #
+    # @param sandbox [Daytona::Sandbox]
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @return [void]
+    def stop(sandbox, timeout = Sandbox::DEFAULT_TIMEOUT) = sandbox.stop(timeout)
+
+    private
+
+    # Creates a sandbox with the specified parameters
+    #
+    # @param params [Daytona::CreateSandboxFromSnapshotParams, Daytona::CreateSandboxFromImageParams] Sandbox creation parameters
+    # @param timeout [Numeric] Maximum wait time in seconds (defaults to 60 s).
+    # @param on_snapshot_create_logs [Proc]
+    # @return [Daytona::Sandbox] The created sandbox
+    # @raise [Daytona::Sdk::Error] If auto_stop_interval or auto_archive_interval is negative
+    def _create(params, timeout: 60, on_snapshot_create_logs: nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      raise Sdk::Error, 'Timeout must be a non-negative number' if timeout.negative?
+
+      start_time = Time.now
+
+      raise Sdk::Error, 'auto_stop_interval must be a non-negative integer' if params.auto_stop_interval&.negative?
+
+      if params.auto_archive_interval&.negative?
+        raise Sdk::Error, 'auto_archive_interval must be a non-negative integer'
+      end
+
+      create_sandbox = DaytonaApiClient::CreateSandbox.new(
+        user: params.os_user,
+        env: params.env_vars || {},
+        labels: params.labels,
+        public: params.public,
+        target: config.target,
+        auto_stop_interval: params.auto_stop_interval,
+        auto_archive_interval: params.auto_archive_interval,
+        auto_delete_interval: params.auto_delete_interval,
+        volumes: params.volumes,
+        network_block_all: params.network_block_all,
+        network_allow_list: params.network_allow_list
+      )
+
+      create_sandbox.snapshot = params.snapshot if params.respond_to?(:snapshot)
+
+      if params.respond_to?(:image) && params.image.is_a?(String)
+        create_sandbox.build_info = DaytonaApiClient::CreateBuildInfo.new(
+          dockerfile_content: Image.base(params.image).dockerfile
+        )
+      elsif params.respond_to?(:image) && params.image.is_a?(Image)
+        create_sandbox.build_info = DaytonaApiClient::CreateBuildInfo.new(
+          context_hashes: SnapshotService.process_image_context(object_storage_api, params.image),
+          dockerfile_content: params.image.dockerfile
+        )
+      end
+
+      if params.respond_to?(:resources)
+        create_sandbox.cpu = params.resources&.cpu
+        create_sandbox.memory = params.resources&.memory
+        create_sandbox.disk = params.resources&.disk
+        create_sandbox.gpu = params.resources&.gpu
+      end
+
+      response = sandbox_api.create_sandbox(create_sandbox)
+
+      if response.state == DaytonaApiClient::SandboxState::PENDING_BUILD && on_snapshot_create_logs
+        uri = URI.parse(sandbox_api.api_client.config.base_url)
+        uri.path = "/api/sandbox/#{response.id}/build-logs"
+        uri.query = 'follow=true'
+
+        headers = {}
+        sandbox_api.api_client.update_params_for_auth!(headers, nil, ['bearer'])
+        Util.stream_async(uri:, headers:, on_chunk: on_snapshot_create_logs)
+      end
+
+      sandbox = to_sandbox(sandbox_dto: response, code_toolbox: code_toolbox_from_labels(response.labels))
+
+      if sandbox.state != DaytonaApiClient::SandboxState::STARTED
+        sandbox.wait_for_sandbox_start([0.001, timeout - (Time.now - start_time)].max)
+      end
+
+      sandbox
+    end
+
+    # @return [void]
+    # @raise [Daytona::Sdk::Error]
+    def ensure_access_token_defined
+      return if config.api_key
+
+      raise Sdk::Error, 'API key or JWT token is required' unless config.jwt_token
+      raise Sdk::Error, 'Organization ID is required when using JWT token' unless config.organization_id
+    end
+
+    # @return [DaytonaApiClient::ApiClient]
+    def build_api_client
+      DaytonaApiClient::ApiClient.new(api_client_config).tap do |client|
+        client.default_headers[HEADER_SOURCE] = SOURCE_RUBY
+        client.default_headers[HEADER_SDK_VERSION] = Sdk::VERSION
+        client.default_headers[HEADER_ORGANIZATION_ID] = config.organization_id if config.jwt_token
+      end
+    end
+
+    # @return [DaytonaApiClient::Configuration]
+    def api_client_config
+      DaytonaApiClient::Configuration.new.configure do |api_config|
+        uri = URI(config.api_url)
+        api_config.scheme = uri.scheme
+        api_config.host = uri.host
+        api_config.base_path = uri.path
+
+        api_config.access_token_getter = proc { config.api_key || config.jwt_token }
+        api_config
+      end
+    end
+
+    # @param sandbox_dto [DaytonaApiClient::Sandbox]
+    # @param code_toolbox [Daytona::SandboxPythonCodeToolbox, Daytona::SandboxTsCodeToolbox]
+    # @return [Daytona::Sandbox]
+    def to_sandbox(sandbox_dto:, code_toolbox:)
+      Sandbox.new(sandbox_dto:, config:, sandbox_api:, toolbox_api:, code_toolbox:)
+    end
+
+    # Converts a language to a code toolbox
+    #
+    # @param language [Symbol]
+    # @return [Daytona::CodeToolbox]
+    # @raise [Daytona::Sdk::Error] If the language is not supported
+    def code_toolbox_from_language(language)
+      case language
+      when CodeLanguage::PYTHON, nil
+        SandboxPythonCodeToolbox.new
+      when SandboxTsCodeToolbox, CodeLanguage::TYPESCRIPT
+        SandboxTsCodeToolbox.new
+      else
+        raise Sdk::Error, "Unsupported language: #{language}"
+      end
+    end
+
+    # Get code toolbox from Sandbox labels
+    #
+    # @param labels [Hash<String, String>]
+    # @return [Daytona::CodeToolbox]
+    def code_toolbox_from_labels(labels) = code_toolbox_from_language(labels[LABEL_CODE_TOOLBOX_LANGUAGE]&.to_sym)
+
+    SOURCE_RUBY = 'ruby-sdk'
+    private_constant :SOURCE_RUBY
+
+    HEADER_SOURCE = 'X-Daytona-Source'
+    private_constant :HEADER_SOURCE
+
+    HEADER_SDK_VERSION = 'X-Daytona-SDK-Version'
+    private_constant :HEADER_SDK_VERSION
+
+    HEADER_ORGANIZATION_ID = 'X-Daytona-Organization-ID'
+    private_constant :HEADER_ORGANIZATION_ID
+
+    LABEL_CODE_TOOLBOX_LANGUAGE = 'code-toolbox-language'
+    private_constant :LABEL_CODE_TOOLBOX_LANGUAGE
+  end
+end

data/lib/daytona/file_system.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'fileutils'
+
+module Daytona
+  class FileSystem
+    # @return [String] The Sandbox ID
+    attr_reader :sandbox_id
+
+    # @return [DaytonaApiClient::ToolboxApi] API client for Sandbox operations
+    attr_reader :toolbox_api
+
+    # Initializes a new FileSystem instance.
+    #
+    # @param sandbox_id [String] The Sandbox ID
+    # @param toolbox_api [DaytonaApiClient::ToolboxApi] API client for Sandbox operations
+    def initialize(sandbox_id:, toolbox_api:)
+      @sandbox_id = sandbox_id
+      @toolbox_api = toolbox_api
+    end
+
+    # Creates a new directory in the Sandbox at the specified path with the given
+    # permissions.
+    #
+    # @param path [String] Path where the folder should be created. Relative paths are resolved based
+    #   on the sandbox working directory.
+    # @param mode [String] Folder permissions in octal format (e.g., "755" for rwxr-xr-x).
+    # @return [void]
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # Create a directory with standard permissions
+    #   sandbox.fs.create_folder("workspace/data", "755")
+    #
+    #   # Create a private directory
+    #   sandbox.fs.create_folder("workspace/secrets", "700")
+    def create_folder(path, mode)
+      Sdk.logger.debug("Creating folder #{path} with mode #{mode}")
+      toolbox_api.create_folder(sandbox_id, path, mode)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to create folder: #{e.message}"
+    end
+
+    # Deletes a file from the Sandbox.
+    #
+    # @param path [String] Path to the file to delete. Relative paths are resolved based on the sandbox working directory.
+    # @param recursive [Boolean] If the file is a directory, this must be true to delete it.
+    # @return [void]
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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)
+    def delete_file(path, recursive: false)
+      toolbox_api.delete_file(sandbox_id, path, { recursive: })
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to delete file: #{e.message}"
+    end
+
+    # Gets detailed information about a file or directory, including its
+    # size, permissions, and timestamps.
+    #
+    # @param path [String] Path to the file or directory. Relative paths are resolved based
+    #   on the sandbox working directory.
+    # @return [DaytonaApiClient::FileInfo] Detailed file information
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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
+    def get_file_info(path)
+      toolbox_api.get_file_info(sandbox_id, path)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to get file info: #{e.message}"
+    end
+
+    # Lists files and directories in a given path and returns their information, similar to the ls -l command.
+    #
+    # @param path [String] Path to the directory to list contents from. Relative paths are resolved
+    #   based on the sandbox working directory.
+    # @return [Array<DaytonaApiClient::FileInfo>] List of file and directory information
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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(', ')}"
+    def list_files(path)
+      toolbox_api.list_files(sandbox_id, { path: })
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to list files: #{e.message}"
+    end
+
+    # 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.
+    #
+    # @param remote_path [String] Path to the file in the Sandbox. Relative paths are resolved based
+    #   on the sandbox working directory.
+    # @param local_path [String, nil] Optional path to save the file locally. If provided, the file will be saved to disk.
+    # @return [File, nil] The file if local_path is nil, otherwise nil
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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"
+    def download_file(remote_path, local_path = nil) # rubocop:disable Metrics/MethodLength
+      file = toolbox_api.download_file(sandbox_id, remote_path)
+
+      if local_path
+
+        parent_dir = File.dirname(local_path)
+        FileUtils.mkdir_p(parent_dir) unless parent_dir == '.'
+
+        File.binwrite(local_path, file.open.read)
+        nil
+      else
+        file
+      end
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to download file: #{e.message}"
+    end
+
+    # Uploads a file to the specified path in the Sandbox. If a file already exists at
+    # the destination path, it will be overwritten.
+    #
+    # @param source [String, IO] File contents as a string/bytes or a local file path or IO object.
+    # @param remote_path [String] Path to the destination file. Relative paths are resolved based on
+    #   the sandbox working directory.
+    # @return [void]
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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")
+    def upload_file(source, remote_path) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      if source.is_a?(String) && File.exist?(source)
+        # Source is a file path
+        File.open(source, 'rb') { |file| toolbox_api.upload_file(sandbox_id, remote_path, { file: }) }
+      elsif source.respond_to?(:read)
+        # Source is an IO object
+        toolbox_api.upload_file(sandbox_id, remote_path, { file: source })
+      else
+        # Source is string content - create a temporary file
+        Tempfile.create('daytona_upload') do |file|
+          file.binmode
+          file.write(source)
+          file.rewind
+          toolbox_api.upload_file(sandbox_id, remote_path, { file: })
+        end
+      end
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to upload file: #{e.message}"
+    end
+
+    # Uploads multiple files to the Sandbox. If files already exist at the destination paths,
+    # they will be overwritten.
+    #
+    # @param files [Array<FileUpload>] List of files to upload.
+    # @return [void]
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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)
+    def upload_files(files)
+      files.each { |file_upload| upload_file(file_upload.source, file_upload.destination) }
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to upload files: #{e.message}"
+    end
+
+    # Searches for files containing a pattern, similar to the grep command.
+    #
+    # @param 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.
+    # @param pattern [String] Search pattern to match against file contents.
+    # @return [Array<DaytonaApiClient::Match>] List of matches found in files
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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
+    def find_files(path, pattern)
+      toolbox_api.find_in_files(sandbox_id, path, pattern)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to find files: #{e.message}"
+    end
+
+    # Searches for files and directories whose names match the specified pattern.
+    # The pattern can be a simple string or a glob pattern.
+    #
+    # @param path [String] Path to the root directory to start search from. Relative paths are resolved
+    #   based on the sandbox working directory.
+    # @param pattern [String] Pattern to match against file names. Supports glob
+    #   patterns (e.g., "*.rb" for Ruby files).
+    # @return [DaytonaApiClient::SearchFilesResponse]
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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"
+    def search_files(path, pattern)
+      toolbox_api.search_files(sandbox_id, path, pattern)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to search files: #{e.message}"
+    end
+
+    # Moves or renames a file or directory. The parent directory of the destination must exist.
+    #
+    # @param source [String] Path to the source file or directory. Relative paths are resolved
+    #   based on the sandbox working directory.
+    # @param destination [String] Path to the destination. Relative paths are resolved based on
+    #   the sandbox working directory.
+    # @return [void]
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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"
+    #   )
+    def move_files(source, destination)
+      toolbox_api.move_file(sandbox_id, source, destination)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to move files: #{e.message}"
+    end
+
+    # Performs search and replace operations across multiple files.
+    #
+    # @param files [Array<String>] List of file paths to perform replacements in. Relative paths are
+    #   resolved based on the sandbox working directory.
+    # @param pattern [String] Pattern to search for.
+    # @param new_value [String] Text to replace matches with.
+    # @return [Array<DaytonaApiClient::ReplaceResult>] List of results indicating replacements made in each file
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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
+    def replace_in_files(files:, pattern:, new_value:)
+      replace_request = DaytonaApiClient::ReplaceRequest.new(
+        files: files,
+        pattern: pattern,
+        new_value: new_value
+      )
+      toolbox_api.replace_in_files(sandbox_id, replace_request)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to replace in files: #{e.message}"
+    end
+
+    # Sets permissions and ownership for a file or directory. Any of the parameters can be nil
+    # to leave that attribute unchanged.
+    #
+    # @param path [String] Path to the file or directory. Relative paths are resolved based on
+    #   the sandbox working directory.
+    # @param mode [String, nil] File mode/permissions in octal format (e.g., "644" for rw-r--r--).
+    # @param owner [String, nil] User owner of the file.
+    # @param group [String, nil] Group owner of the file.
+    # @return [void]
+    # @raise [Daytona::Sdk::Error] If the operation fails
+    #
+    # @example
+    #   # 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"
+    #   )
+    def set_file_permissions(path:, mode: nil, owner: nil, group: nil)
+      opts = {}
+      opts[:mode] = mode if mode
+      opts[:owner] = owner if owner
+      opts[:group] = group if group
+
+      toolbox_api.set_file_permissions(sandbox_id, path, opts)
+    rescue StandardError => e
+      raise Sdk::Error, "Failed to set file permissions: #{e.message}"
+    end
+  end
+end