class LittleGhost::Sandbox

A Sandbox decides what an agent may do with files and processes. Applications can place that work on the host, in a container or VM, or behind a remote execution service without changing their tools.

class ContainerSandbox < LittleGhost::Sandbox
  def initialize(workspace:, container:)
    super(workspace:)
    @container = container
  end

  def read(path, context: nil)
    context&.check!
    @container.read(path)
  end

  def execute_program(command, timeout:, context: nil, **)
    result = @container.run(
      command, timeout:, cancellation: context&.cancellation_token
    )
    Execution.new(**result)
  end
end

Implementations confine paths to workspace, honor RunContext cancellation, enforce time and output limits, and return Execution from process operations.

Attributes

workspace [R]

Workspace whose files and processes this sandbox governs.

Public Class Methods

new (workspace:)

Source

# File lib/little_ghost/sandbox.rb, line 76
def initialize(workspace:)
  @workspace = workspace
end

Binds the sandbox to workspace.

Public Instance Methods

close ()

Source

# File lib/little_ghost/sandbox.rb, line 134
def close
  nil
end

Releases sandbox resources. Runs close the sandbox before its workspace.

execute (command, timeout:, context: nil, max_output_bytes: 1_000_000, **options)

Source

# File lib/little_ghost/sandbox.rb, line 115
def execute(command, timeout:, context: nil, max_output_bytes: 1_000_000, **options)
  execute_program(
    ["/bin/sh", "-c", String(command)],
    timeout:,
    context:,
    max_output_bytes:,
    **options
  )
end

Executes command through /bin/sh.

Prefer execute_program for model-controlled arguments so shell syntax is not interpreted.

execute_program (command, timeout:, context: nil, max_output_bytes: 1_000_000, environment: {}, inherit_environment: false)

Source

# File lib/little_ghost/sandbox.rb, line 129
def execute_program(command, timeout:, context: nil, max_output_bytes: 1_000_000, environment: {}, inherit_environment: false)
  raise NotImplementedError, "#{self.class} does not support program execution"
end

Executes an argument vector without shell interpretation.

Implementations must enforce timeout and max_output_bytes. Environment inheritance is disabled by default to avoid leaking process credentials.

list (path = ".", context: nil)

Source

# File lib/little_ghost/sandbox.rb, line 97
def list(path = ".", context: nil)
  raise NotImplementedError, "#{self.class} does not support filesystem listings"
end

Lists entries at a workspace-relative directory path.

open (run: nil)

Source

# File lib/little_ghost/sandbox.rb, line 84
def open(run: nil)
  self
end

Opens any run-scoped resources and makes the sandbox ready for tools.

read (path, context: nil)

Source

# File lib/little_ghost/sandbox.rb, line 92
def read(path, context: nil)
  raise NotImplementedError, "#{self.class} does not support filesystem reads"
end

Reads UTF-8 text at a workspace-relative path.

replace (path, old_text, new_text, context: nil)

Source

# File lib/little_ghost/sandbox.rb, line 107
def replace(path, old_text, new_text, context: nil)
  raise NotImplementedError, "#{self.class} does not support filesystem edits"
end

Replaces one exact old_text occurrence with new_text.

writable? ()

Source

# File lib/little_ghost/sandbox.rb, line 89
def writable? = false

Indicates whether filesystem mutation is allowed.

write (path, content, context: nil)

Source

# File lib/little_ghost/sandbox.rb, line 102
def write(path, content, context: nil)
  raise NotImplementedError, "#{self.class} does not support filesystem writes"
end

Writes content to a workspace-relative path.