# Class LittleGhost::Sandbox

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Sandbox.html

A Sandbox governs filesystem operations and child processes that explicitly
pass through it. Built-in filesystem and shell Tools use their bound Sandbox.
A custom Ruby Tool remains trusted application code unless it delegates work
to that Sandbox or one of its Scopes.

    LittleGhost.configure do |config|
      config.sandbox = {
        provider: :native,
        files: {root: :read_write, source: :read_only},
        runtime_paths: {home: :read_write},
        network: :none
      }
    end

A backend reports the policy and capabilities it actually enforces. File
operations stay within declared Workspace paths. Process operations honor
cancellation and configured limits, then return an
[Execution](Sandbox/Execution.md).

A backend's isolation mechanism still relies on its outer host, kernel or VM,
dependencies, trusted configuration, and deliberately exposed paths. Sandbox
policy does not apply to provider requests or arbitrary Ruby code in the
application process.

See the [Workspaces and Sandboxes guide](../sandboxing.md)
for the path model, built-in backends, Scopes, process ownership, and
networking boundaries.

## Inheritance

`LittleGhost::Sandbox < Object`

## Attributes

<a id="attribute-i-limits"></a>
### `limits` (R)

File and process output bounds enforced by this Sandbox.

<a id="attribute-i-policy"></a>
### `policy` (R)

Normalized policy requested by trusted application configuration.

<a id="attribute-i-workspace"></a>
### `workspace` (R)

Workspace whose files and processes this sandbox governs.

## Class methods

<a id="method-c-new"></a>
### `.new`

```ruby
.new(workspace:, policy: nil, profiles: {}, limits: {})
```

Binds the sandbox to `workspace`.

<a id="method-c-probe"></a>
### `.probe`

```ruby
.probe(name, **options)
```

Reports whether a registered backend can start in the current environment
without creating a Run-owned sandbox.

<a id="method-c-register_provider"></a>
### `.register_provider`

```ruby
.register_provider(name, implementation)
```

Registers a trusted backend class under a configuration symbol.

<a id="method-c-resolve_provider"></a>
### `.resolve_provider`

```ruby
.resolve_provider(name)
```

Resolves a registered backend without silently falling back.

## Instance methods

<a id="method-i-allows-3F"></a>
### `#allows?`

```ruby
#allows?(operation, path = nil)
```

Indicates whether an operation is allowed by this sandbox and optional virtual
`path`.

<a id="method-i-capabilities"></a>
### `#capabilities`

```ruby
#capabilities()
```

Operations and network modes implemented by this backend.

<a id="method-i-close"></a>
### `#close`

```ruby
#close()
```

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

<a id="method-i-effective_policy"></a>
### `#effective_policy`

```ruby
#effective_policy()
```

Policy the backend enforces. Backends may fill a documented default or report
an unavoidable effective value, but reject unsupported requested rules instead
of silently claiming enforcement.

<a id="method-i-execute"></a>
### `#execute`

```ruby
#execute(command, timeout:, context: nil, max_output_bytes: nil, **options)
```

Executes `command` through `/bin/sh`.

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

<a id="method-i-execute_program"></a>
### `#execute_program`

```ruby
#execute_program(command, timeout:, context: nil, max_output_bytes: nil, environment: {}, inherit_environment: false, **options)
```

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; both
policy and the individual call must opt in before a backend may inherit.

<a id="method-i-list"></a>
### `#list`

```ruby
#list(path = ".", context: nil)
```

Lists entries at a workspace-relative or absolute virtual directory `path`.

<a id="method-i-open"></a>
### `#open`

```ruby
#open(run: nil)
```

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

<a id="method-i-read"></a>
### `#read`

```ruby
#read(path, context: nil)
```

Reads UTF-8 text at a workspace-relative or absolute virtual `path`.

<a id="method-i-replace"></a>
### `#replace`

```ruby
#replace(path, old_text, new_text, context: nil)
```

Replaces one exact `old_text` occurrence at a workspace-relative or absolute
virtual `path` with `new_text`.

<a id="method-i-scope"></a>
### `#scope`

```ruby
#scope(profile = nil, files: nil, runtime_paths: nil, capabilities: nil, network: nil)
```

Produces a non-owning capability-reduced view for tools or child agents. The
caller must pass and use that Scope; retaining this parent Sandbox retains its
broader authority.

<a id="method-i-start_program"></a>
### `#start_program`

```ruby
#start_program(command, context: nil, environment: {}, inherit_environment: false, **options)
```

Starts an owned, duplex child process for framed protocols and other
interactive programs. The returned session owns the child process group.

<a id="method-i-supports-3F"></a>
### `#supports?`

```ruby
#supports?(feature, value = nil)
```

Indicates whether the backend implements `feature`.

<a id="method-i-writable-3F"></a>
### `#writable?`

```ruby
#writable?()
```

Indicates whether filesystem mutation is allowed.

<a id="method-i-write"></a>
### `#write`

```ruby
#write(path, content, context: nil)
```

Writes `content` to a workspace-relative or absolute virtual `path`.