Ruby SDK Sandbox reference

See Overview for configuration examples and Lifecycle for state management. See Error handling for cross-SDK behavior.

Sandbox

Class methods

Microsandbox::Sandbox.create()

Microsandbox::Sandbox.create(name, **options) # => Sandbox

Example

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 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()

Microsandbox::Sandbox.builder(name) # => SandboxBuilder

Create a chainable sandbox builder.

Parameters

nameString

Sandbox name.

Returns

SandboxBuilder

Configuration builder.

Microsandbox::Sandbox.start()

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()

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.list()

Microsandbox::Sandbox.list(**options) # => Hash

Example

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()

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()

Microsandbox::Sandbox.with(name, **options) { |sandbox| } # => Object

Example

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()

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.

Example

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

sandbox.name # => String

Returns

String

Sandbox name.

sandbox.owns_lifecycle?

sandbox.owns_lifecycle? # => Boolean

Returns

Boolean

Whether this connection owns the sandbox lifecycle.

sandbox.backend

sandbox.backend # => String

Returns

String

Selected backend: local or cloud.

sandbox.status

sandbox.status # => String

Returns

String

Current lifecycle status, fetched from the backend.

sandbox.last_failure_message

sandbox.last_failure_message # => String | nil

Returns

String | nil

Most recent recorded failure, if available.

sandbox.kill()

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()

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()

sandbox.ping # => Hash

Check sandbox responsiveness.

Returns

Hash

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

sandbox.touch()

sandbox.touch # => Hash

Record activity to refresh the sandbox idle timer.

Returns

Hash

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

sandbox.metrics()

sandbox.metrics # => SandboxMetrics

Read a metrics sample.

Returns

SandboxMetrics

Metrics sample; call to_h for its fields.

sandbox.request_kill()

sandbox.request_kill # => nil

Request forced termination without waiting for shutdown. Local-only.

Returns

nil

No return value.

sandbox.detach()

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()

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()

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()

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

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()

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. 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()

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()

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()

builder.image(value) # => SandboxBuilder

OCI image reference.

Parameters

valueString

OCI image reference.

Returns

SandboxBuilder

The builder, for chaining.

builder.cpus()

builder.cpus(value) # => SandboxBuilder

Initial virtual CPU count.

Parameters

valueInteger

Initial virtual CPU count.

Returns

SandboxBuilder

The builder, for chaining.

builder.max_cpus()

builder.max_cpus(value) # => SandboxBuilder

Maximum virtual CPU count.

Parameters

valueInteger

Maximum virtual CPU count.

Returns

SandboxBuilder

The builder, for chaining.

builder.memory()

builder.memory(value) # => SandboxBuilder

Initial memory in MiB.

Parameters

valueInteger

Initial memory in MiB.

Returns

SandboxBuilder

The builder, for chaining.

builder.max_memory()

builder.max_memory(value) # => SandboxBuilder

Maximum memory in MiB.

Parameters

valueInteger

Maximum memory in MiB.

Returns

SandboxBuilder

The builder, for chaining.

builder.env()

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()

builder.workdir(value) # => SandboxBuilder

Guest working directory.

Parameters

valueString

Guest working directory.

Returns

SandboxBuilder

The builder, for chaining.

builder.shell()

builder.shell(value) # => SandboxBuilder

Shell used for shell commands.

Parameters

valueString

Shell used for shell commands.

Returns

SandboxBuilder

The builder, for chaining.

builder.hostname()

builder.hostname(value) # => SandboxBuilder

Guest hostname.

Parameters

valueString

Guest hostname.

Returns

SandboxBuilder

The builder, for chaining.

builder.user()

builder.user(value) # => SandboxBuilder

Guest user.

Parameters

valueString

Guest user.

Returns

SandboxBuilder

The builder, for chaining.

builder.intercept_tls()

builder.intercept_tls # => SandboxBuilder

Enable TLS interception while preserving existing network settings. Sandbox.create also accepts intercept_tls: true.

builder.detached()

builder.detached(value) # => SandboxBuilder

Start locally in the background.

Parameters

valueBoolean

Start locally in the background.

Returns

SandboxBuilder

The builder, for chaining.

builder.ephemeral()

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()

builder.max_duration(value) # => SandboxBuilder

Maximum lifetime in seconds.

Parameters

valueInteger

Maximum lifetime in seconds.

Returns

SandboxBuilder

The builder, for chaining.

builder.idle_timeout()

builder.idle_timeout(value) # => SandboxBuilder

Idle timeout in seconds.

Parameters

valueInteger

Idle timeout in seconds.

Returns

SandboxBuilder

The builder, for chaining.

builder.replace()

builder.replace # => SandboxBuilder

Replace an existing sandbox with this name.

Returns

SandboxBuilder

The builder, for chaining.

builder.root_disk()

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()

builder.disable_network # => SandboxBuilder

Disable sandbox networking.

Returns

SandboxBuilder

The builder, for chaining.

builder.proxy()

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()

builder.quiet_logs # => SandboxBuilder

Suppress sandbox log output.

Returns

SandboxBuilder

The builder, for chaining.

builder.entrypoint()

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()

builder.init(value) # => SandboxBuilder

Guest init program.

Parameters

valueString

Guest init program.

Returns

SandboxBuilder

The builder, for chaining.

builder.label()

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()

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()

builder.create # => Sandbox

Example

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 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()

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()

builder.http { |h| h.deny_response(true).deny_message(message) } # => SandboxBuilder

Denial responses are disabled by default. Call h.deny_response(true) to enable readable 403 responses. Optionally set deny_message to customize the body; {host} names the blocked hostname. Setting a message alone does not enable responses. Enabling requires a supporting local runtime; cloud rejects it. See HTTP denial responses for which requests receive a response.

Example

builder = Microsandbox::Sandbox.builder("agent")
  .image("python")
  .http { |h| h.deny_response(true).deny_message("{host} is blocked. Ask the user to allow it.") }

The same option is available when creating a sandbox:

Microsandbox::Sandbox.create(
  "agent",
  image: "python",
  network: { allowed_hosts: ["example.com"], allowed_ports: [80, 443] },
  http: { deny_response: true, deny_message: "{host} is blocked. Ask the user to allow it." }
)

SandboxHandle

handle.name

handle.name # => String

Returns

String

Sandbox name.

handle.status

handle.status # => String

Returns

String

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

handle.config_json

handle.config_json # => String

Returns

String

Saved desired configuration as JSON.

handle.active_config_json

handle.active_config_json # => String | nil

Returns

String | nil

Configuration used for the active run, when available.

handle.last_failure_message

handle.last_failure_message # => String | nil

Returns

String | nil

Failure message captured by this handle, if available.

handle.kill()

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()

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()

handle.ping # => Hash

Check sandbox responsiveness.

Returns

Hash

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

handle.touch()

handle.touch # => Hash

Record activity to refresh the sandbox idle timer.

Returns

Hash

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

handle.metrics()

handle.metrics # => SandboxMetrics

Read a metrics sample.

Returns

SandboxMetrics

Metrics sample; call to_h for its fields.

handle.refresh()

handle.refresh # => SandboxHandle

Fetch current metadata for this sandbox.

Returns

SandboxHandle

A refreshed handle; assign the returned value.

handle.connect()

handle.connect # => Sandbox

Connect to the running sandbox without starting it.

Returns

Sandbox

Live sandbox connection.

handle.start()

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()

handle.remove # => nil

Remove this stopped sandbox. The handle remains bound to its original identity.

Returns

nil

No return value.

handle.id

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()

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()

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()

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()

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()

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()

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()

metrics.to_h # => Hash

Example

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.

Example

begin
  stale_handle.destroy
rescue Microsandbox::SandboxReplacedError => error
  warn error.message
end

Installation requirements

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.85 or newer to build it locally. Blocking native calls release Ruby’s global VM lock (GVL), allowing other Ruby threads to run.

Example

require "microsandbox"

Microsandbox.install unless Microsandbox.installed?

Managed jobs

Run and reconnect to background commands. See Background jobs for lifecycle, retention, and runtime limits.

sandbox.exec_detached()

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.

Example

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()

sandbox.get_job(id) # => Job

Retrieve a retained job by ID. Also available on SandboxHandle.

sandbox.list_jobs()

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

job.id # => String

The job ID within its sandbox.

job.inspect

job.inspect # => JobInfo

Read current metadata without starting a stopped sandbox.

job.wait

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

job.signal(signal) # => nil

Send a Linux signal to the process group.

job.kill

job.kill # => nil

Request SIGKILL. Wait separately to confirm exit.

job.eof

job.eof # => nil

Permanently close pipe input after accepted bytes. PTYs reject this operation; use terminal control characters instead.

job.logs

job.logs(tail: nil, since: nil, until: nil, sources: [], from_cursor: nil) # => Array<JobLogEntry>

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

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

job.follow_logs(**options) # => JobLogStream

Stream logs with following enabled. Accepts the same filters as logs.

job.attach

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

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

attachment.write_stdin(bytes) # => nil

Write a String of up to 16 KiB through the input-owning attachment.

attachment.resize

attachment.resize(rows, cols) # => nil

Resize the job terminal. Each dimension must fit an unsigned 16-bit integer.

attachment.detach

attachment.detach # => nil

Release the attachment when finished. The job and its input remain open. close is an alias.

JobLogStream

stream.next

stream.next # => JobLogEntry or nil

Read the next log entry. each iterates entries and closes the stream on exit.

stream.close

stream.close # => nil

Stop observing logs. This does not stop the job.

⌘I

​Sandbox

​Microsandbox::Sandbox.create()

​Microsandbox::Sandbox.builder()

​Microsandbox::Sandbox.start()

​Microsandbox::Sandbox.get()

​Microsandbox::Sandbox.list()

​Microsandbox::Sandbox.remove()

​Microsandbox::Sandbox.with()

​Microsandbox::Sandbox.connect_or_create()

​sandbox.name

​sandbox.owns_lifecycle?

​sandbox.backend

​sandbox.status

​sandbox.last_failure_message

​sandbox.kill()

​sandbox.wait_until_stopped()

​sandbox.ping()

​sandbox.touch()

​sandbox.metrics()

​sandbox.request_kill()

​sandbox.detach()

​sandbox.stop()

​sandbox.stop_with_timeout()

​sandbox.request_stop()

​sandbox.id

​sandbox.wait_for_status()

​sandbox.restart()

​sandbox.destroy()

​SandboxBuilder

​builder.image()

​builder.cpus()

​builder.max_cpus()

​builder.memory()

​builder.max_memory()

​builder.env()

​builder.workdir()

​builder.shell()

​builder.hostname()

​builder.user()

​builder.intercept_tls()

​builder.detached()

​builder.ephemeral()

​builder.max_duration()

​builder.idle_timeout()

​builder.replace()

​builder.root_disk()

​builder.disable_network()

​builder.proxy()

​builder.quiet_logs()

​builder.entrypoint()

​builder.init()

​builder.label()

​builder.replace_with_timeout()

​builder.create()

​builder.connect_or_create()

​builder.http()

​SandboxHandle

​handle.name

​handle.status

​handle.config_json

​handle.active_config_json

​handle.last_failure_message

​handle.kill()

​handle.wait_until_stopped()

​handle.ping()

​handle.touch()

​handle.metrics()

​handle.refresh()

​handle.connect()

​handle.start()

​handle.remove()

​handle.id

​handle.stop()

​handle.stop_with_timeout()

​handle.connect_or_start()

​handle.wait_for_status()

​handle.restart()

​handle.destroy()

​SandboxMetrics

​metrics.to_h()

Sandbox

Microsandbox::Sandbox.create()

Microsandbox::Sandbox.builder()

Microsandbox::Sandbox.start()

Microsandbox::Sandbox.get()

Microsandbox::Sandbox.list()

Microsandbox::Sandbox.remove()

Microsandbox::Sandbox.with()

Microsandbox::Sandbox.connect_or_create()

sandbox.name

sandbox.owns_lifecycle?

sandbox.backend

sandbox.status

sandbox.last_failure_message

sandbox.kill()

sandbox.wait_until_stopped()

sandbox.ping()

sandbox.touch()

sandbox.metrics()

sandbox.request_kill()

sandbox.detach()

sandbox.stop()

sandbox.stop_with_timeout()

sandbox.request_stop()

sandbox.id

sandbox.wait_for_status()

sandbox.restart()

sandbox.destroy()

SandboxBuilder

builder.image()

builder.cpus()

builder.max_cpus()

builder.memory()

builder.max_memory()

builder.env()

builder.workdir()

builder.shell()

builder.hostname()

builder.user()

builder.intercept_tls()

builder.detached()

builder.ephemeral()

builder.max_duration()

builder.idle_timeout()

builder.replace()

builder.root_disk()

builder.disable_network()

builder.proxy()

builder.quiet_logs()

builder.entrypoint()

builder.init()

builder.label()

builder.replace_with_timeout()

builder.create()

builder.connect_or_create()

builder.http()

SandboxHandle

handle.name

handle.status

handle.config_json

handle.active_config_json

handle.last_failure_message

handle.kill()

handle.wait_until_stopped()

handle.ping()

handle.touch()

handle.metrics()

handle.refresh()

handle.connect()

handle.start()

handle.remove()

handle.id

handle.stop()

handle.stop_with_timeout()

handle.connect_or_start()

handle.wait_for_status()

handle.restart()

handle.destroy()

SandboxMetrics

metrics.to_h()