# Class LittleGhost::Sandboxes::Unrestricted

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Sandboxes/Unrestricted.html

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::Sandboxes::Unrestricted.new(workspace:)
    sandbox.read("README.md").lines.first # => "# LittleGhost\n"

Reads return valid UTF-8 text. Writes preserve the supplied String bytes.
Paths may be relative to the workspace or absolute within a declared virtual
mount. Traversal components are rejected, and every path is checked against
its configured mount 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.

## Inheritance

`LittleGhost::Sandboxes::Unrestricted < LittleGhost::Sandbox`

## Attributes

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

Reports the host permissions this backend actually uses. In particular,
unrestricted execution cannot make the host root filesystem read-only.

## Class methods

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

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

Configures a host sandbox with an explicit policy and resource limits.

## Instance methods

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

```ruby
#capabilities()
```

Reports host execution and the bounded filesystem operations exposed by this
instance. +isolation: :none+ is deliberate: unrestricted execution is not a
security boundary.

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

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

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`.

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

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

Produces a newline-delimited, sorted directory listing. Directories end in
`/`.

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

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

Opens the sandbox and verifies that the workspace root has not changed.

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

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

Reads a bounded UTF-8 file within the workspace.

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

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

Replaces exactly one occurrence of `old_text` in a writable file.

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

```ruby
#start_program(command, context: nil, environment: {}, inherit_environment: false,
        scope: nil, cwd: nil, output_bytes: nil, memory_bytes: nil, cpu_seconds: nil, file_bytes: nil,
        allow_subprocesses: true)
```

Starts a bounded host process. This remains unrestricted host execution, not a
containment boundary.

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

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

Indicates whether this sandbox accepts filesystem mutations.

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

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

Writes a bounded String without following a symbolic-link target.