--- title: Sandbox "og:title": Ruby SDK Sandbox reference description: Create and manage microVM sandboxes with the Ruby SDK. keywords: ["Ruby SDK", "Ruby sandbox", "microsandbox sandbox"] --- See [Overview](/sandboxes/overview) for configuration examples and [Lifecycle](/sandboxes/lifecycle) for state management. See [Error handling](/sdk/errors) for cross-SDK behavior. ## Sandbox

Class methods

#### Microsandbox::Sandbox.create() ```ruby Microsandbox::Sandbox.create(name, **options) # => Sandbox ``` ```ruby sandbox = Microsandbox::Sandbox.create("worker", image: "alpine", memory: 512) ``` Create and start a sandbox. An existing name is an error unless replacement is requested. See [Networking](/sdk/ruby/networking) for network, proxy, and secret options.

Parameters

nameString

Sandbox name.

imageString

OCI image reference.

cpusInteger

Initial virtual CPU count.

max_cpusInteger

Maximum virtual CPU count.

memoryInteger

Initial memory in MiB.

max_memoryInteger

Maximum memory in MiB.

envHash

Environment variables with string keys and values.

labelsHash

Labels with string keys and values.

workdirString

Guest working directory.

shellString

Shell used for shell commands.

hostnameString

Guest hostname.

userString

Guest user.

detachedBoolean

Start locally in the background.

ephemeralBoolean

Remove sandbox state when its lifecycle ends.

max_durationInteger

Maximum lifetime in seconds.

idle_timeoutInteger

Idle timeout in seconds.

replaceBoolean

Replace an existing sandbox with this name.

replace_timeoutNumeric

Finite, non-negative replacement timeout in seconds.

root_diskInteger

Managed root disk size in MiB.

disable_networkBoolean

Disable sandbox networking.

networkSymbol | Hash

Use :none or the allowlist hash documented in the Networking reference.

proxyOutboundProxy

SOCKS proxy configuration; see the Networking reference.

secretsArray<Hash>

Secret injection entries; see the Networking reference.

quiet_logsBoolean

Suppress sandbox log output.

entrypointArray<String>

Override the image entrypoint; creation does not execute it.

initString

Guest init program.

pull_policyString

Image pull policy: if_missing (or if-missing), always, or never.

scriptsHash

Named scripts with string keys and values.

slugString

Human-readable sandbox slug.

Returns

Sandbox

Live sandbox connection.

#### Microsandbox::Sandbox.builder() ```ruby Microsandbox::Sandbox.builder(name) # => SandboxBuilder ``` Create a chainable sandbox builder.

Parameters

nameString

Sandbox name.

Returns

SandboxBuilder

Configuration builder.

#### Microsandbox::Sandbox.start() ```ruby Microsandbox::Sandbox.start(name, detached: false) # => Sandbox ``` Start an existing sandbox.

Parameters

nameString

Sandbox name.

detachedBoolean

Start locally in the background; defaults to false.

Returns

Sandbox

Live sandbox connection.

#### Microsandbox::Sandbox.get() ```ruby Microsandbox::Sandbox.get(name) # => SandboxHandle ``` Obtain persisted metadata without connecting to the guest agent.

Parameters

nameString

Sandbox name.

Returns

SandboxHandle

Metadata handle bound to this sandbox identity.

#### Microsandbox::Sandbox.recover_storage() ```ruby Microsandbox::Sandbox.recover_storage( name, selections: {}, accept_selected_view: false, legacy_writers_stopped: false ) # => StorageRecovery ``` Import or resume storage for a stopped local sandbox. Inspect it first with [storage diagnostics](/sdk/setup#inspect-legacy-storage). See [sandbox storage migration](/migrations/sandbox-storage) for maintenance requirements and recovery limits.

Parameters

selectionsHash<String, String>

Exact IDs from storage diagnosis, with disk ID keys and candidate ID values. Omit or leave empty to import or resume the validated current view.

accept_selected_viewBoolean

Default false. Required for explicit selections, which may omit writes from other disk branches.

legacy_writers_stoppedBoolean

Default false. On macOS, confirm that legacy VMs across all homes are stopped and new writers are prevented during recovery.

Returns

StorageRecovery

name (string) identifies the sandbox. ready (boolean) confirms protected storage is ready, and originals_retained (boolean) confirms the original disks were retained.

#### Microsandbox::Sandbox.list() ```ruby Microsandbox::Sandbox.list(**options) # => Hash ``` ```ruby page = Microsandbox::Sandbox.list(limit: 20) page["sandboxes"].each { |handle| puts handle.name } ``` List sandboxes with optional pagination and label filtering.

Parameters

cursorString

Optional cursor from the previous page.

limitInteger

Optional maximum page size.

labelsHash

Optional label filter with string keys and values.

Returns

Hash

String keys: sandboxes (Array<SandboxHandle>) and next_cursor (String or nil).

#### Microsandbox::Sandbox.remove() ```ruby Microsandbox::Sandbox.remove(name) # => nil ``` Remove a stopped sandbox and its local state. Use destroy to stop and remove a sandbox.

Parameters

nameString

Sandbox name.

Returns

nil

No return value.

#### Microsandbox::Sandbox.with() ```ruby Microsandbox::Sandbox.with(name, **options) { |sandbox| } # => Object ``` ```ruby Microsandbox::Sandbox.with("worker", image: "alpine") do |sandbox| puts sandbox.exec("echo", ["hello"]).stdout end ``` Create a sandbox and yield it to the block. Gracefully stop it when the block exits, including on an exception. This does not remove persisted sandbox state. Without a block, return the created sandbox.

Parameters

nameString

Sandbox name.

optionsHash

The same creation options as create().

Returns

Object

The block result, or a Sandbox when no block is supplied.

#### Microsandbox::Sandbox.connect_or_create() ```ruby Microsandbox::Sandbox.connect_or_create(name, **options) # => Sandbox ``` Reuse or create the sandbox with this name. The method connects when it is running, waits while it is starting, starts it when it is created, stopped, or crashed, and creates it only when the name is unused. Options apply only to a new sandbox, and concurrent callers reuse the same sandbox. Replace options are rejected because they request a different sandbox. ```ruby 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.

Parameters

nameString

Sandbox name.

optionsHash

Creation options, applied only when creating a new sandbox.

Returns

Sandbox

Live sandbox connection.

Instance methods

#### sandbox.name ```ruby sandbox.name # => String ```

Returns

String

Sandbox name.

#### sandbox.owns_lifecycle? ```ruby sandbox.owns_lifecycle? # => Boolean ```

Returns

Boolean

Whether this connection owns the sandbox lifecycle.

#### sandbox.backend ```ruby sandbox.backend # => String ```

Returns

String

Selected backend: local or cloud.

#### sandbox.status ```ruby sandbox.status # => String ```

Returns

String

Current lifecycle status, fetched from the backend: created, starting, running, draining, paused, stopped, or crashed.

#### sandbox.last_failure_message ```ruby sandbox.last_failure_message # => String | nil ```

Returns

String | nil

Most recent recorded failure, if available.

#### sandbox.kill() ```ruby sandbox.kill(timeout: nil) # => nil ``` Force termination and wait for shutdown. Omit timeout for an unbounded wait. Force termination is local-only.

Parameters

timeoutNumeric

Optional finite, non-negative timeout in seconds. May also be passed positionally, but not both ways.

Returns

nil

No return value.

#### sandbox.wait_until_stopped() ```ruby sandbox.wait_until_stopped # => Hash ``` Wait for termination without a built-in timeout.

Returns

Hash

Stop result with string keys; see Stop result below.

#### sandbox.ping() ```ruby sandbox.ping # => Hash ``` Check sandbox responsiveness.

Returns

Hash

String keys: name (String) and latency_ms (Integer).

#### sandbox.touch() ```ruby sandbox.touch # => Hash ``` Record activity to refresh the sandbox idle timer.

Returns

Hash

String keys: name (String) and activity_seq (Integer).

#### sandbox.metrics() Local-only ```ruby sandbox.metrics # => SandboxMetrics ``` Read a metrics sample.

Returns

SandboxMetrics

Metrics sample; call to_h for its fields.

#### sandbox.request_kill() ```ruby sandbox.request_kill # => nil ``` Request forced termination without waiting for shutdown. Local-only.

Returns

nil

No return value.

#### sandbox.detach() ```ruby sandbox.detach # => nil ``` Detach from the local runtime. This consumes the live connection; subsequent operations on it fail.

Returns

nil

No return value.

#### sandbox.stop() ```ruby sandbox.stop # => nil sandbox.stop(timeout: 30) # Existing optional bounded form ``` Request graceful shutdown and wait for this exact sandbox run to finish, including local runtime ownership release. There is no built-in deadline or automatic force-kill. A supplied `timeout:` bounds the wait without changing graceful shutdown into forced termination. These semantics require the matching updated native extension and runtime.

Parameters

timeoutNumeric

Optional finite, non-negative deadline in seconds; no deadline when omitted.

Returns

nil

No return value.

#### sandbox.stop_with_timeout() ```ruby sandbox.stop_with_timeout(seconds) # => nil ``` Bound graceful shutdown with an explicit finite, non-negative timeout. The deadline covers local transition ownership, request dispatch, and termination observation. Expiry raises `Microsandbox::Error` without force-killing; zero expires before sending a request. Call `kill` separately when forced termination is intended.

Parameters

secondsNumeric

Finite, non-negative timeout in seconds.

Returns

nil

No return value.

#### sandbox.request_stop() ```ruby sandbox.request_stop # => nil ``` Send the graceful shutdown request without waiting for termination or scheduling a force-kill. Pair with `wait_until_stopped` to observe completion.

Returns

nil

No return value.

#### sandbox.id ```ruby 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.

Returns

String

Stable sandbox identity.

#### sandbox.wait_for_status() ```ruby sandbox.wait_for_status(status) # => SandboxHandle ``` Wait without a built-in timeout until this exact sandbox reaches the requested [lifecycle status](#sandbox-status). Returns a refreshed metadata handle. Ruby's `Timeout.timeout` does not reliably interrupt the native wait. Use an SDK operation with an explicit timeout when you need a bounded shutdown.

Parameters

statusString

Target lifecycle status.

Returns

SandboxHandle

Refreshed metadata handle.

#### sandbox.restart() ```ruby 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 how long shutdown can take, 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.

Parameters

forceBoolean

Use forced termination; defaults to false and is local-only.

timeoutNumeric | nil

Shutdown timeout in seconds; nil uses the SDK default of ten seconds.

detachedBoolean

Start locally in the background; defaults to false.

Returns

Sandbox

Live connection to the restarted sandbox.

#### sandbox.destroy() ```ruby 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.

Parameters

forceBoolean

Use forced termination; defaults to false.

timeoutNumeric | nil

Shutdown timeout in seconds; nil uses the SDK default of ten seconds.

Returns

nil

No return value.

## SandboxBuilder #### builder.image() ```ruby builder.image(value) # => SandboxBuilder ``` OCI image reference.

Parameters

valueString

OCI image reference.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.cpus() ```ruby builder.cpus(value) # => SandboxBuilder ``` Initial virtual CPU count.

Parameters

valueInteger

Initial virtual CPU count.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.max_cpus() ```ruby builder.max_cpus(value) # => SandboxBuilder ``` Maximum virtual CPU count.

Parameters

valueInteger

Maximum virtual CPU count.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.memory() ```ruby builder.memory(value) # => SandboxBuilder ``` Initial memory in MiB.

Parameters

valueInteger

Initial memory in MiB.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.max_memory() ```ruby builder.max_memory(value) # => SandboxBuilder ``` Maximum memory in MiB.

Parameters

valueInteger

Maximum memory in MiB.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.env() ```ruby builder.env(key, value) # => SandboxBuilder ``` Environment variables with string keys and values.

Parameters

keyString

Environment variable name.

valueString

Environment variable value.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.workdir() ```ruby builder.workdir(value) # => SandboxBuilder ``` Guest working directory.

Parameters

valueString

Guest working directory.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.shell() ```ruby builder.shell(value) # => SandboxBuilder ``` Shell used for shell commands.

Parameters

valueString

Shell used for shell commands.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.hostname() ```ruby builder.hostname(value) # => SandboxBuilder ``` Guest hostname.

Parameters

valueString

Guest hostname.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.user() ```ruby builder.user(value) # => SandboxBuilder ``` Guest user.

Parameters

valueString

Guest user.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.intercept_tls() ```ruby builder.intercept_tls # => SandboxBuilder ``` Enable [TLS interception](/networking/tls) while preserving existing network settings. `Sandbox.create` also accepts `intercept_tls: true`. #### builder.detached() ```ruby builder.detached(value) # => SandboxBuilder ``` Start locally in the background.

Parameters

valueBoolean

Start locally in the background.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.ephemeral() ```ruby builder.ephemeral(value) # => SandboxBuilder ``` Remove sandbox state when its lifecycle ends.

Parameters

valueBoolean

Remove sandbox state when its lifecycle ends.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.max_duration() ```ruby builder.max_duration(value) # => SandboxBuilder ``` Maximum lifetime in seconds.

Parameters

valueInteger

Maximum lifetime in seconds.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.idle_timeout() ```ruby builder.idle_timeout(value) # => SandboxBuilder ``` Idle timeout in seconds.

Parameters

valueInteger

Idle timeout in seconds.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.replace() ```ruby builder.replace # => SandboxBuilder ``` Replace an existing sandbox with this name.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.root_disk() ```ruby builder.root_disk(value) # => SandboxBuilder ``` Managed root disk size in MiB.

Parameters

valueInteger

Managed root disk size in MiB.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.disable_network() ```ruby builder.disable_network # => SandboxBuilder ``` Disable sandbox networking.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.proxy() ```ruby builder.proxy(value) # => SandboxBuilder ``` SOCKS proxy configuration; see the Networking reference.

Parameters

valueOutboundProxy

SOCKS proxy configuration; see the Networking reference.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.quiet_logs() ```ruby builder.quiet_logs # => SandboxBuilder ``` Suppress sandbox log output.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.entrypoint() ```ruby builder.entrypoint(value) # => SandboxBuilder ``` Override the image entrypoint; creation does not execute it.

Parameters

valueArray<String>

Override the image entrypoint; creation does not execute it.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.init() ```ruby builder.init(value) # => SandboxBuilder ``` Guest init program.

Parameters

valueString

Guest init program.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.label() ```ruby builder.label(key, value) # => SandboxBuilder ``` Add a label.

Parameters

keyString

Label key.

valueString

Label value.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.replace_with_timeout() ```ruby builder.replace_with_timeout(seconds) # => SandboxBuilder ``` Replace an existing sandbox with a bounded wait.

Parameters

secondsNumeric

Finite, non-negative timeout in seconds.

Returns

SandboxBuilder

The builder, for chaining.

#### builder.create() ```ruby builder.create # => Sandbox ``` ```ruby sandbox = Microsandbox::Sandbox.builder("worker") .image("alpine") .memory(512) .create ``` Create and start the configured sandbox. This consumes the builder; it cannot be reused.

Returns

Sandbox

Live sandbox connection.

The chainable setters above also have bang forms, such as `image!`, which mutate the builder and return `nil`. See [VSock](/sdk/ruby/vsock) for `vsock` and `vsock_dgram`. Network allowlists, secret entries, pull policy, scripts, and slug are creation keywords, not Ruby builder methods. #### builder.connect_or_create() ```ruby Microsandbox::Sandbox.builder(name).connect_or_create # => Sandbox ``` Create or reuse the configured sandbox, with the same behavior as `Microsandbox::Sandbox.connect_or_create`. This consumes the builder.

Returns

Sandbox

Live sandbox connection.

#### builder.http() ```ruby builder.http { |h| h.deny_response(true).deny_response_format("json").network_deny_message(message) } # => SandboxBuilder ``` Local denial responses default to JSON `403` errors. Call `h.deny_response(false)` to disable them. `network_deny_message` and `secret_deny_message` customize the respective messages. Requires a supporting local runtime; cloud behavior is unchanged. See [HTTP denial responses](/networking/overview#http-denial-responses). ```ruby builder = Microsandbox::Sandbox.builder("agent") .image("python") .http { |h| h.deny_response(true).deny_response_format("json").network_deny_message("Request blocked. Ask the user for access.") } ``` The same option is available when creating a sandbox: ```ruby Microsandbox::Sandbox.create( "agent", image: "python", network: { allowed_hosts: ["example.com"], allowed_ports: [80, 443] }, http: { deny_response: true, deny_response_format: "json", network_deny_message: "Request blocked. Ask the user for access." } ) ``` ## SandboxHandle #### handle.name ```ruby handle.name # => String ```

Returns

String

Sandbox name.

#### handle.status ```ruby handle.status # => String ```

Returns

String

Status captured by this metadata handle. Call refresh for current metadata.

#### handle.config_json ```ruby handle.config_json # => String ```

Returns

String

Saved desired configuration as JSON.

#### handle.active_config_json ```ruby handle.active_config_json # => String | nil ```

Returns

String | nil

Configuration used for the active run, when available.

#### handle.last_failure_message ```ruby handle.last_failure_message # => String | nil ```

Returns

String | nil

Failure message captured by this handle, if available.

#### handle.kill() ```ruby handle.kill(timeout: nil) # => nil ``` Force termination and wait for shutdown. Omit timeout for an unbounded wait. Force termination is local-only.

Parameters

timeoutNumeric

Optional finite, non-negative timeout in seconds. May also be passed positionally, but not both ways.

Returns

nil

No return value.

#### handle.wait_until_stopped() ```ruby handle.wait_until_stopped # => Hash ``` Wait for termination without a built-in timeout.

Returns

Hash

Stop result with string keys; see Stop result below.

#### handle.ping() ```ruby handle.ping # => Hash ``` Check sandbox responsiveness.

Returns

Hash

String keys: name (String) and latency_ms (Integer).

#### handle.touch() ```ruby handle.touch # => Hash ``` Record activity to refresh the sandbox idle timer.

Returns

Hash

String keys: name (String) and activity_seq (Integer).

#### handle.metrics() Local-only ```ruby handle.metrics # => SandboxMetrics ``` Read a metrics sample.

Returns

SandboxMetrics

Metrics sample; call to_h for its fields.

#### handle.refresh() ```ruby handle.refresh # => SandboxHandle ``` Fetch current metadata for this sandbox.

Returns

SandboxHandle

A refreshed handle; assign the returned value.

#### handle.connect() ```ruby handle.connect # => Sandbox ``` Connect to the running sandbox without starting it.

Returns

Sandbox

Live sandbox connection.

#### handle.start() ```ruby handle.start(detached: false) # => Sandbox ``` Start this existing sandbox.

Parameters

detachedBoolean

Start locally in the background; defaults to false.

Returns

Sandbox

Live sandbox connection.

#### handle.remove() ```ruby handle.remove # => nil ``` Remove this stopped sandbox. The handle remains bound to its original identity.

Returns

nil

No return value.

#### handle.id ```ruby handle.id # => String ``` Opaque stable identity captured by this handle. Receiver lifecycle calls remain bound to this value.

Returns

String

Stable sandbox identity.

#### handle.stop() ```ruby handle.stop # No built-in deadline handle.stop(timeout: 30) # Existing optional bounded form ``` Request graceful shutdown for this exact sandbox run and wait for termination and local runtime ownership release. `stop` has no built-in timeout. Both bounded forms raise `Microsandbox::Error` on expiry without force-killing; zero expires before sending a request. A stale identity is refused rather than stopping a replacement. On cloud, a timeout limits the SDK wait; an accepted stop may continue server-side.

Parameters

timeoutNumeric

Optional finite, non-negative deadline in seconds; no deadline when omitted.

Returns

nil

No return value.

#### handle.stop_with_timeout() ```ruby handle.stop_with_timeout(seconds) # => nil ``` Request graceful shutdown and wait up to the supplied deadline. Timeout does not force-kill the sandbox; zero expires before sending a request.

Parameters

secondsNumeric

Finite, non-negative timeout in seconds.

Returns

nil

No return value.

#### handle.connect_or_start() ```ruby 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.

Parameters

detachedBoolean

Start locally in the background if needed; defaults to false.

Returns

Sandbox

Live sandbox connection.

#### handle.wait_for_status() ```ruby 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.

Parameters

statusString

Target lifecycle status.

Returns

SandboxHandle

Refreshed metadata handle.

#### handle.restart() ```ruby handle.restart(force: false, timeout: nil, detached: false) # => Sandbox ``` Restart this exact sandbox with the same state and option semantics as `Sandbox#restart`.

Parameters

forceBoolean

Use forced termination; defaults to false and is local-only.

timeoutNumeric | nil

Shutdown timeout in seconds; nil uses the SDK default of ten seconds.

detachedBoolean

Start locally in the background; defaults to false.

Returns

Sandbox

Live connection to the restarted sandbox.

#### handle.destroy() ```ruby 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.

Parameters

forceBoolean

Use forced termination; defaults to false.

timeoutNumeric | nil

Shutdown timeout in seconds; nil uses the SDK default of ten seconds.

Returns

nil

No return value.

## SandboxMetrics #### metrics.to_h() ```ruby metrics.to_h # => Hash ``` ```ruby sample = sandbox.metrics.to_h puts sample["memory_bytes"] ``` Return the metrics sample as a hash with string keys.

Returns

Hash

Metrics fields below.

Fields

cpu_percentFloat

CPU utilization percentage.

vcpu_time_nsInteger

Accumulated virtual CPU time in nanoseconds.

memory_bytesInteger

Memory usage in bytes.

memory_limit_bytesInteger

Memory limit in bytes.

disk_read_bytesInteger

Bytes read from disk.

disk_write_bytesInteger

Bytes written to disk.

net_rx_bytesInteger

Network bytes received.

net_tx_bytesInteger

Network bytes sent.

uptime_msInteger

Uptime in milliseconds.

timestampString

RFC 3339 sample timestamp.

## Stop result

Fields

nameString

Sandbox name.

statusString

Observed terminal status.

exit_codeInteger | nil

Exit code, if available.

signalInteger | nil

Termination signal, if available.

observed_atString

RFC 3339 observation timestamp.

sourceString | nil

Source of the termination observation.

## Identity errors Stale handles raise `Microsandbox::SandboxReplacedError` rather than acting on a replacement with the same name. See [Error handling](/sdk/errors#when-a-sandbox-object-is-stale). ```ruby begin stale_handle.destroy rescue Microsandbox::SandboxReplacedError => error warn error.message end ``` ## Installation requirements ```bash gem install microsandbox ``` Ruby 3.3, 3.4, and 4.0 are supported. When a matching platform gem is available, it carries the native extension; otherwise the source gem requires Rust 1.89 or newer to build it locally. Blocking native calls release Ruby's global VM lock (GVL), allowing other Ruby threads to run. ```ruby require "microsandbox" Microsandbox.install unless Microsandbox.installed? ``` ## Managed jobs Run and reconnect to background commands. See [Background jobs](/sandboxes/commands#background-jobs) for lifecycle, retention, and runtime limits. #### sandbox.exec_detached() ```ruby sandbox.exec_detached(cmd, args = [], **options) # => Job ``` Start a job after confirming guest startup. Accepts the `exec` options: `cwd`, `user`, `env`, `timeout`, `stdin`, `tty`, and `rlimits`. Stdin defaults to `:pipe`; `:null` closes it, and a String supplies at most 64 KiB followed by EOF. ```ruby job = sb.exec_detached("cat", cwd: "/tmp") io = job.attach io.write_stdin("hello\n") io.detach found = sb.get_job(job.id) found.eof result = found.wait output = found.logs page = sb.list_jobs(all: true, limit: 50) ``` #### sandbox.get_job() ```ruby sandbox.get_job(id) # => Job ``` Retrieve a retained job by ID. Also available on `SandboxHandle`. #### sandbox.list_jobs() ```ruby sandbox.list_jobs(all: false, limit: 50, cursor: nil) # => JobPage ``` List active jobs, or include retained history with the all option. Returns items and a next-page cursor. Default page size: 50; range: 1–100. Also available on `SandboxHandle`. ### Job #### job.id ```ruby job.id # => String ``` The job ID within its sandbox. #### job.inspect ```ruby job.inspect # => JobInfo ``` Read current metadata without starting a stopped sandbox. #### job.wait ```ruby job.wait # => JobExit ``` Wait for a confirmed exit without consuming output. The result contains the exit code, success flag, and timeout flag. Blocking operations release the Ruby GVL. #### job.signal ```ruby job.signal(signal) # => nil ``` Send a Linux signal to the process group. #### job.kill ```ruby job.kill # => nil ``` Request SIGKILL. Wait separately to confirm exit. #### job.eof ```ruby job.eof # => nil ``` Permanently close pipe input after accepted bytes. PTYs reject this operation; use terminal control characters instead. #### job.logs ```ruby job.logs(tail: nil, since: nil, until: nil, sources: [], from_cursor: nil) # => Array ``` Read retained output. Entries contain original bytes, a source, a Unix-millisecond timestamp, and an opaque cursor belonging to this job. `since` is inclusive and `until` exclusive, both in Unix milliseconds; `from_cursor` cannot be combined with `since`. #### job.log_stream ```ruby job.log_stream(tail: nil, since: nil, until: nil, sources: [], from_cursor: nil, follow: false) # => JobLogStream ``` Read retained output and optionally follow new records. Use `each` for automatic cleanup or close the stream explicitly. #### job.follow_logs ```ruby job.follow_logs(**options) # => JobLogStream ``` Stream logs with following enabled. Accepts the same filters as `logs`. #### job.attach ```ruby job.attach(read_only: false, replay_bytes: nil, cursor: nil) # => JobAttachment ``` Attach to live I/O. Only one attachment may own input; read-only observers may coexist. Recent-byte replay and cursor replay are alternatives. ### JobAttachment #### attachment.recv ```ruby attachment.recv # => JobEvent or nil ``` Read an output, history-gap, or completion event. `each` iterates events and detaches on exit. Input and output can run on separate Ruby threads. #### attachment.write_stdin ```ruby attachment.write_stdin(bytes) # => nil ``` Write a String of up to 16 KiB through the input-owning attachment. #### attachment.resize ```ruby attachment.resize(rows, cols) # => nil ``` Resize the job terminal. Each dimension must fit an unsigned 16-bit integer. #### attachment.detach ```ruby attachment.detach # => nil ``` Release the attachment when finished. The job and its input remain open. `close` is an alias. ### JobLogStream #### stream.next ```ruby stream.next # => JobLogEntry or nil ``` Read the next log entry. `each` iterates entries and closes the stream on exit. #### stream.close ```ruby stream.close # => nil ``` Stop observing logs. This does not stop the job. ## Nested virtualization `nested_virt: true | false` controls nested virtualization for a local sandbox. Omit it to inherit configuration (off by default). See [nested VM snapshots](/sandboxes/snapshots#nested-vm-snapshots) for requirements. ```ruby sandbox = Microsandbox::Sandbox.create("nested", image: "alpine", nested_virt: true) ```