> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Ruby SDK - Sandbox lifecycle API reference

Create and control a microVM sandbox from Ruby. The SDK supports local and cloud backends; blocking native calls release Ruby's GVL so other Ruby threads can continue running. See [Lifecycle](/sandboxes/lifecycle) for the shared state model and [Error handling](/sdk/errors) for cross-SDK behavior.

## Installation

```bash theme={null}
gem install microsandbox
```

Ruby 3.1 and newer are supported. When a matching platform gem is available, it carries the native extension; otherwise the source gem requires Rust 1.85 or newer to build it locally.

```ruby theme={null}
require "microsandbox"

Microsandbox.install unless Microsandbox.installed?
```

## Convergent creation

#### <span className="msb-recv">Microsandbox::Sandbox.</span><span className="msb-hn">connect\_or\_create()</span>

```ruby theme={null}
Microsandbox::Sandbox.connect_or_create(name, **options) # => Sandbox
```

Converge on the current persisted sandbox by name. The method connects when it is running, waits through `starting`, starts it when it is `created`, `stopped`, or `crashed`, and creates it only when the name is absent. Options apply only to creation; an existing sandbox keeps its persisted configuration. Concurrent callers converge on the winning identity. Replace options are rejected because replacement conflicts with convergence.

```ruby theme={null}
sandbox = Microsandbox::Sandbox.connect_or_create(
  "worker",
  image: "python",
  memory: 1024,
  env: { "ROLE" => "worker" }
)
```

Use `Sandbox.create` when name conflicts must remain an error, or explicit replace options when the old identity should be discarded.

## SandboxBuilder

#### <span className="msb-recv">builder.</span><span className="msb-hn">connect\_or\_create()</span>

```ruby theme={null}
Microsandbox::Sandbox.builder(name).connect_or_create # => Sandbox
```

Builder terminal with the same convergence, existing-configuration, concurrency, and replace-option behavior as `Microsandbox::Sandbox.connect_or_create`.

## Sandbox

A live sandbox connection returned by `create`, `connect_or_create`, `start`, `connect_or_start`, or `restart`.

#### <span className="msb-recv">sandbox.</span><span className="msb-hn">id</span>

```ruby theme={null}
sandbox.id # => String
```

Opaque stable identity of the persisted sandbox. It remains unchanged across stop and restart and changes when a removed name is recreated. Use it for equality, logging, and correlation; do not parse it.

#### <span className="msb-recv">sandbox.</span><span className="msb-hn">wait\_for\_status()</span>

```ruby theme={null}
sandbox.wait_for_status(status) # => SandboxHandle
```

Wait without a built-in timeout until this exact sandbox reaches one of `created`, `starting`, `running`, `draining`, `paused`, `stopped`, or `crashed`. Returns a refreshed metadata handle. Use Ruby's `Timeout.timeout` or an application cancellation mechanism when a deadline is required.

#### <span className="msb-recv">sandbox.</span><span className="msb-hn">restart()</span>

```ruby theme={null}
sandbox.restart(force: false, timeout: nil, detached: false) # => Sandbox
```

Restart this exact sandbox. Defaults to graceful shutdown, the SDK's ten-second timeout, and attached local start. A created, stopped, or crashed sandbox starts directly; a starting sandbox is observed until it settles. Set `force: true` to kill, `timeout:` in seconds to change shutdown convergence, or `detached: true` for a local background start.

On microsandbox cloud, graceful restart is supported, but timeout expiry cannot escalate to force kill. `force: true` is local-only, and `detached:` affects only local process ownership.

#### <span className="msb-recv">sandbox.</span><span className="msb-hn">destroy()</span>

```ruby theme={null}
sandbox.destroy(force: false, timeout: nil) # => nil
```

Stop and remove this exact sandbox. Defaults to graceful shutdown with the SDK's ten-second timeout. Identity checks refuse to delete a same-name replacement.

## SandboxHandle

Obtain a metadata handle without opening the guest-agent connection:

```ruby theme={null}
handle = Microsandbox::Sandbox.get("worker")
```

#### <span className="msb-recv">handle.</span><span className="msb-hn">id</span>

```ruby theme={null}
handle.id # => String
```

Opaque stable identity captured by this handle. Receiver lifecycle calls remain bound to this value.

#### <span className="msb-recv">handle.</span><span className="msb-hn">connect\_or\_start()</span>

```ruby theme={null}
handle.connect_or_start(detached: false) # => Sandbox
```

Connect when this exact sandbox is running, wait through `starting`, or start it when it is `created`, `stopped`, or `crashed`. `draining` and `paused` are rejected. `detached: true` affects only a required local start; connecting to an already-running sandbox does not change ownership.

#### <span className="msb-recv">handle.</span><span className="msb-hn">wait\_for\_status()</span>

```ruby theme={null}
handle.wait_for_status(status) # => SandboxHandle
```

Wait until this exact sandbox reaches `status`, returning a refreshed handle. The method does not have a built-in timeout.

#### <span className="msb-recv">handle.</span><span className="msb-hn">restart()</span>

```ruby theme={null}
handle.restart(force: false, timeout: nil, detached: false) # => Sandbox
```

Restart this exact sandbox with the same state and option semantics as `Sandbox#restart`.

#### <span className="msb-recv">handle.</span><span className="msb-hn">destroy()</span>

```ruby theme={null}
handle.destroy(force: false, timeout: nil) # => nil
```

Stop and remove this exact sandbox. A stale handle refuses to destroy a replacement that reused the name.

## Identity errors

Ruby currently surfaces stale identity protection through `Microsandbox::Error`. The message includes `was replaced`; unlike Rust, TypeScript, Python, and Go, the Ruby SDK does not yet expose a dedicated `SandboxReplacedError` subclass.

```ruby theme={null}
begin
  stale_handle.destroy
rescue Microsandbox::Error => error
  raise unless error.message.include?("was replaced")
end
```

See [Stale receiver identities](/sdk/errors#stale-receiver-identities) for the typed equivalents in the other SDKs and [Identity-safe receivers](/sandboxes/lifecycle#identity-safe-receivers) for the race this prevents.

## Live lifecycle example

Run `ruby examples/lifecycle_convergence.rb` from `sdk/ruby` to exercise convergent creation and reuse, stable identity, connect, wait, exec, restart, destroy, same-name replacement, and stale-handle rejection against a live microVM.