Class: E2B::Services::Filesystem

Inherits:
BaseService show all
Defined in:
lib/e2b/services/filesystem.rb

Overview

Filesystem operations for E2B sandbox

Provides methods for reading, writing, and managing files in the sandbox. Uses envd RPC for filesystem operations and REST endpoints for file transfer.

Examples:

# Write a file
sandbox.files.write("/home/user/hello.txt", "Hello, World!")

# Read a file
content = sandbox.files.read("/home/user/hello.txt")

# List directory
entries = sandbox.files.list("/home/user")

Constant Summary

Constants inherited from BaseService

BaseService::DEFAULT_USERNAME, BaseService::ENVD_DEFAULT_USER_VERSION, BaseService::ENVD_PORT, BaseService::ENVD_RECURSIVE_WATCH_VERSION

Instance Method Summary collapse

Methods inherited from BaseService

#initialize

Constructor Details

This class inherits a constructor from E2B::Services::BaseService

Instance Method Details

#exists?(path, user: nil, request_timeout: 30) ⇒ Boolean

Check if a path exists

Only NotFoundError is treated as “does not exist”. Other errors (auth, network, server) propagate so callers can distinguish “file is gone” from “we couldn’t ask”.

Parameters:

  • path (String) —

    Path to check

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 30) —

    Request timeout in seconds

Returns:

  • (Boolean) 


120
121
122
123
124
125
 
# File 'lib/e2b/services/filesystem.rb', line 120

def exists?(path, user: nil, request_timeout: 30)
  get_info(path, user: user, request_timeout: request_timeout)
  true
rescue E2B::NotFoundError
  false
end

#get_info(path, user: nil, request_timeout: 30) ⇒ Models::EntryInfo

Get file/directory information using filesystem RPC

Parameters:

  • path (String) —

    Path to get info for

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 30) —

    Request timeout in seconds

Returns:



133
134
135
136
137
138
139
140
141
 
# File 'lib/e2b/services/filesystem.rb', line 133

def get_info(path, user: nil, request_timeout: 30)
  response = envd_rpc("filesystem.Filesystem", "Stat",
    body: { path: path },
    timeout: request_timeout,
    headers: user_auth_headers(user))

  entry_data = extract_entry(response)
  Models::EntryInfo.from_hash(entry_data)
end

#list(path, depth: 1, user: nil, request_timeout: 60) ⇒ Array<Models::EntryInfo> Also known as: list_files

List directory contents using filesystem RPC

Examples:

entries = sandbox.files.list("/home/user")
entries.each { |e| puts "#{e.name} (#{e.type})" }

Parameters:

  • path (String) —

    Directory path

  • depth (Integer) (defaults to: 1) —

    Recursion depth (default: 1, only immediate children)

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 60) —

    Request timeout in seconds

Returns:



100
101
102
103
104
105
106
107
108
 
# File 'lib/e2b/services/filesystem.rb', line 100

def list(path, depth: 1, user: nil, request_timeout: 60)
  response = envd_rpc("filesystem.Filesystem", "ListDir",
    body: { path: path, depth: depth },
    timeout: request_timeout,
    headers: user_auth_headers(user))

  entries = extract_entries(response)
  entries.map { |e| Models::EntryInfo.from_hash(e) }
end

#make_dir(path, user: nil, request_timeout: 30) ⇒ Boolean Also known as: mkdir, create_folder

Create a directory

Parameters:

  • path (String) —

    Directory path to create

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 30) —

    Request timeout in seconds

Returns:

  • (Boolean) —

    true if created successfully



178
179
180
181
182
183
184
 
# File 'lib/e2b/services/filesystem.rb', line 178

def make_dir(path, user: nil, request_timeout: 30)
  envd_rpc("filesystem.Filesystem", "MakeDir",
    body: { path: path },
    timeout: request_timeout,
    headers: user_auth_headers(user))
  true
end

#read(path, format: "text", user: nil, request_timeout: 120) ⇒ String Also known as: read_file

Default username for file operations Read file content

Examples:

content = sandbox.files.read("/home/user/config.json")

Parameters:

  • path (String) —

    File path in the sandbox

  • format (String) (defaults to: "text") —

    Return format: “text” (default), “bytes”, or “stream”

  • user (String) (defaults to: nil) —

    Username context for the operation

  • request_timeout (Integer) (defaults to: 120) —

    Request timeout in seconds

Returns:

  • (String) —

    File content



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/e2b/services/filesystem.rb', line 38

def read(path, format: "text", user: nil, request_timeout: 120)
  url = build_file_url("/files", path: path, user: user)
  response = rest_get(url, timeout: request_timeout)

  case format
  when "text"
    response.dup.force_encoding("UTF-8")
  when "bytes"
    response.b
  when "stream"
    StringIO.new(response.b)
  else
    raise ArgumentError, "Unsupported read format '#{format}'"
  end
end

#remove(path, user: nil, request_timeout: 30) ⇒ Object Also known as: delete_file

Remove a file or directory

Parameters:

  • path (String) —

    Path to remove

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 30) —

    Request timeout in seconds



148
149
150
151
152
153
 
# File 'lib/e2b/services/filesystem.rb', line 148

def remove(path, user: nil, request_timeout: 30)
  envd_rpc("filesystem.Filesystem", "Remove",
    body: { path: path },
    timeout: request_timeout,
    headers: user_auth_headers(user))
end

#rename(old_path, new_path, user: nil, request_timeout: 30) ⇒ Models::EntryInfo Also known as: move, move_files

Rename/move a file or directory

Parameters:

  • old_path (String) —

    Source path

  • new_path (String) —

    Destination path

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 30) —

    Request timeout in seconds

Returns:



162
163
164
165
166
167
168
169
170
 
# File 'lib/e2b/services/filesystem.rb', line 162

def rename(old_path, new_path, user: nil, request_timeout: 30)
  response = envd_rpc("filesystem.Filesystem", "Move",
    body: { source: old_path, destination: new_path },
    timeout: request_timeout,
    headers: user_auth_headers(user))

  entry_data = extract_entry(response)
  Models::EntryInfo.from_hash(entry_data)
end

#watch_dir(path, recursive: false, user: nil, request_timeout: 30) ⇒ WatchHandle

Watch a directory for filesystem changes

Uses the polling-based CreateWatcher/GetWatcherEvents/RemoveWatcher RPCs.

Examples:

handle = sandbox.files.watch_dir("/home/user/project")
# ... wait for changes ...
events = handle.get_new_events
events.each { |e| puts "#{e.type}: #{e.name}" }
handle.stop

Parameters:

  • path (String) —

    Directory path to watch

  • recursive (Boolean) (defaults to: false) —

    Watch subdirectories recursively

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 30) —

    Request timeout in seconds

Returns:

  • (WatchHandle) —

    Handle for polling events and stopping the watcher

Raises:



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/e2b/services/filesystem.rb', line 202

def watch_dir(path, recursive: false, user: nil, request_timeout: 30)
  if recursive && !supports_recursive_watch?
    raise E2B::TemplateError,
      "You need to update the template to use recursive watching. You can do this by running `e2b template build` in the directory with the template."
  end

  response = envd_rpc("filesystem.Filesystem", "CreateWatcher",
    body: { path: path, recursive: recursive },
    timeout: request_timeout,
    headers: user_auth_headers(user))

  watcher_id = response[:events]&.first&.dig("watcherId") ||
               response["watcherId"] ||
               extract_watcher_id(response)

  raise E2B::E2BError, "Failed to create watcher: no watcher_id returned" unless watcher_id

  rpc_proc = method(:envd_rpc)
  WatchHandle.new(
    watcher_id: watcher_id,
    envd_rpc_proc: rpc_proc,
    headers: user_auth_headers(user)
  )
end

#write(path, data, user: nil, request_timeout: 120) ⇒ Models::WriteInfo Also known as: write_file

Write content to a file using REST upload

Examples:

sandbox.files.write("/home/user/output.txt", "Hello, World!")

Parameters:

  • path (String) —

    File path in the sandbox

  • data (String, IO) —

    Content to write (string or IO object)

  • user (String) (defaults to: nil) —

    Username context for the operation

  • request_timeout (Integer) (defaults to: 120) —

    Request timeout in seconds

Returns:



64
65
66
67
68
69
 
# File 'lib/e2b/services/filesystem.rb', line 64

def write(path, data, user: nil, request_timeout: 120)
  url = build_file_url("/files", path: path, user: user)
  content = data.is_a?(IO) || data.respond_to?(:read) ? data.read : data.to_s
  result = rest_upload(url, content, timeout: request_timeout)
  build_write_info(result, default_path: path)
end

#write_files(files, user: nil, request_timeout: 120) ⇒ Array

Write multiple files at once

Examples:

sandbox.files.write_files([
  { path: "/home/user/a.txt", data: "Content A" },
  { path: "/home/user/b.txt", data: "Content B" }
])

Parameters:

  • files (Array<Hash>) —

    Array of { path:, data: } hashes

  • user (String) (defaults to: nil) —

    Username context

  • request_timeout (Integer) (defaults to: 120) —

    Request timeout in seconds

Returns:

  • (Array) —

    Results for each file



83
84
85
86
87
 
# File 'lib/e2b/services/filesystem.rb', line 83

def write_files(files, user: nil, request_timeout: 120)
  files.map do |file|
    write(file[:path], file[:data] || file[:content], user: user, request_timeout: request_timeout)
  end
end