class LittleGhost::UnrestrictedSandbox
UnrestrictedSandbox is a convenient host-backed sandbox for trusted local work. It offers bounded text-file operations and command execution using only Ruby’s standard library.
workspace = LittleGhost::Workspace.new(root: Dir.pwd) sandbox = LittleGhost::UnrestrictedSandbox.new(workspace:) sandbox.read("README.md").lines.first # => "# LittleGhost\n"
Reads return valid UTF-8 text. Writes preserve the supplied String bytes. Paths must be relative, may not contain .., and are checked against the configured workspace root.
Security and trust
This sandbox is not a security boundary. Commands run directly on the host with the Ruby process’s permissions, and filesystem containment cannot defend against concurrent adversarial mutation. Use an isolated Sandbox implementation for untrusted work.
Public Class Methods
# File lib/little_ghost/unrestricted_sandbox.rb, line 27 def initialize(workspace:, writable: false, max_read_bytes: 1_000_000, max_write_bytes: 1_000_000, max_list_entries: 10_000) super(workspace:) @writable = writable @max_read_bytes = Integer(max_read_bytes) @max_write_bytes = Integer(max_write_bytes) @max_list_entries = Integer(max_list_entries) unless [@max_read_bytes, @max_write_bytes, @max_list_entries].all?(&:positive?) raise ArgumentError, "sandbox limits must be positive" end @root = File.expand_path(workspace.root) capture_root_identity if File.exist?(@root) end
Configures a host sandbox with explicit read, write, and listing limits. Filesystem writes remain disabled unless writable is true.
LittleGhost::Sandbox::new
Public Instance Methods
# File lib/little_ghost/unrestricted_sandbox.rb, line 125 def execute_program( command, timeout:, context: nil, max_output_bytes: 1_000_000, environment: {}, inherit_environment: false ) argv = Array(command).map(&:to_s) raise ToolError, "Command must contain an executable" if argv.empty? || argv.first.empty? timeout = Float(timeout) max_output_bytes = Integer(max_output_bytes) raise ArgumentError, "timeout must be positive" unless timeout.positive? raise ArgumentError, "max_output_bytes must be positive" unless max_output_bytes.positive? stdout, stderr, status = capture( argv, timeout:, context:, max_output_bytes:, environment:, inherit_environment: ) Execution.new(stdout:, stderr:, exit_code: status.exitstatus) end
Executes an argument vector on the host from the workspace root.
Shell syntax is not interpreted. The child starts with an empty environment unless inherit_environment is true, is terminated when the context is cancelled or the timeout expires, and has each output stream truncated to max_output_bytes.
# File lib/little_ghost/unrestricted_sandbox.rb, line 74 def list(path = ".", context: nil) context&.check! directory = existing_path(path, allow_root: true) raise ToolError, "Path is not a directory" unless File.directory?(directory) entries = Dir.children(directory) raise ToolError, "Directory exceeds the listing limit" if entries.length > @max_list_entries entries.sort.map do |entry| File.lstat(File.join(directory, entry)).directory? ? "#{entry}/" : entry end.join("\n") end
Produces a newline-delimited, sorted directory listing. Directories end in /.
Source
# File lib/little_ghost/unrestricted_sandbox.rb, line 42 def open(run: nil) if @root_identity validate_root! else @root = File.realpath(workspace.root) capture_root_identity end self end
Opens the sandbox and verifies that the workspace root has not changed.
Source
# File lib/little_ghost/unrestricted_sandbox.rb, line 56 def read(path, context: nil) context&.check! File.open(existing_path(path), read_flags) do |file| raise ToolError, "Path is not a file" unless file.stat.file? content = file.read(@max_read_bytes + 1) raise ToolError, "File exceeds the read limit" if content.bytesize > @max_read_bytes content.force_encoding(Encoding::UTF_8) raise ToolError, "File is not valid UTF-8 text" unless content.valid_encoding? content end rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError raise ToolError, "File is not valid UTF-8 text" end
Reads a bounded UTF-8 file within the workspace.
# File lib/little_ghost/unrestricted_sandbox.rb, line 107 def replace(path, old_text, new_text, context: nil) context&.check! raise ToolError, "Text to replace cannot be empty" if old_text.empty? content = read(path, context:) occurrences = content.scan(old_text).length raise ToolError, "Text was not found in #{display_path(path)}" if occurrences.zero? raise ToolError, "Text occurs more than once in #{display_path(path)}" if occurrences > 1 write(path, content.sub(old_text, new_text), context:) end
Replaces exactly one occurrence of old_text in a writable file.
Source
# File lib/little_ghost/unrestricted_sandbox.rb, line 53 def writable? = @writable
Indicates whether this sandbox accepts filesystem mutations.
# File lib/little_ghost/unrestricted_sandbox.rb, line 88 def write(path, content, context: nil) context&.check! raise ToolError, "Sandbox is read-only" unless writable? raise ToolError, "Content exceeds the write limit" if content.bytesize > @max_write_bytes flags = File::WRONLY | File::CREAT | File::TRUNC flags |= File::NOFOLLOW if defined?(File::NOFOLLOW) flags |= File::NONBLOCK if defined?(File::NONBLOCK) File.open(writable_path(path), flags, 0o644) do |file| raise ToolError, "Path is not a file" unless file.stat.file? file.write(content) end "Wrote #{content.bytesize} bytes to #{display_path(path)}" rescue Errno::ELOOP raise ToolError, "Write target cannot be a symbolic link" end
Writes a bounded String without following a symbolic-link target.