# Class LittleGhost::Sandboxes::Bubblewrap

Documentation version: Edge

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

Runs each command in a fresh Bubblewrap namespace on Linux. Bubblewrap is
selected explicitly and is never installed or replaced with host execution.
The namespace shares the outer Linux kernel and trusts the configured runtime
roots, mounts, command wrapper, and hosting environment. It governs child
processes, not arbitrary Ruby code in the parent runtime.

## Inheritance

`LittleGhost::Sandboxes::Bubblewrap < LittleGhost::Sandbox::IsolatedBackend`

## Class methods

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

```ruby
.backend_capabilities()
```

Describes the isolation and operations provided by this backend.

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

```ruby
.new(workspace:, policy: nil, profiles: {}, limits: {},
        bubblewrap: DEFAULT_EXECUTABLE, platform: RUBY_PLATFORM,
        socat: "/usr/bin/socat", gateway_options: {}, command_wrapper: nil,
        proc: :new, tmpfs: %w[/tmp /run], masks: [], runtime_roots: RUNTIME_ROOTS,
        uid: nil, gid: nil)
```

Builds a command-scoped Linux namespace sandbox.

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

```ruby
.probe(executable: DEFAULT_EXECUTABLE, platform: RUBY_PLATFORM)
```

Reports whether Bubblewrap is usable on `platform`.

## Instance methods

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

```ruby
#bubblewrap_args(mounts: effective_policy.process_grants(workspace), cwd: workspace.root,
        environment: effective_policy.environment.to_h, inherit_environment: effective_policy.environment.inherit?,
        network: effective_policy.network)
```

Returns the exact Bubblewrap policy arguments used before the command.

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

```ruby
#capabilities()
```

Returns this backend's declared capabilities.

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

```ruby
#close()
```

Stops the policy gateway. Calling `close` more than once is safe.

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

```ruby
#exec_program(command, scope: nil, cwd: nil, environment: {}, inherit_environment: false)
```

Replaces the current process with an interactively attached Bubblewrap command
after applying the same policy and scope validation as #execute.

<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, cwd: nil)
```

Executes `command` in a fresh Bubblewrap namespace.

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

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

Validates dependencies and starts any policy gateway.

<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 duplex process in a fresh Bubblewrap namespace. Descendants are
allowed and remain owned by its PID namespace; Bubblewrap cannot enforce a
per-program request to deny subprocess creation.