Module: Microsandbox

Defined in:
lib/microsandbox.rb,
lib/microsandbox/fs.rb,
lib/microsandbox/image.rb,
lib/microsandbox/errors.rb,
lib/microsandbox/volume.rb,
lib/microsandbox/metrics.rb,
lib/microsandbox/sandbox.rb,
lib/microsandbox/streams.rb,
lib/microsandbox/version.rb,
lib/microsandbox/snapshot.rb,
lib/microsandbox/log_entry.rb,
lib/microsandbox/exec_handle.rb,
lib/microsandbox/exec_output.rb

Overview

Microsandbox — lightweight microVM sandboxes for Ruby.

The runtime is embedded directly in the process via a Rust native extension; there is no daemon to install and no server to connect to. Creating a sandbox spawns a real microVM as a child process.

Examples:

Microsandbox::Sandbox.create("hello", image: "python") do |sb|
  puts sb.exec("python", ["-c", "print('Hello, World!')"]).stdout
end

Defined Under Namespace

Classes: Error, ExecEvent, ExecHandle, ExecOutput, ExecStdin, ExitStatus, FS, FsEntry, FsMetadata, Image, ImageDetail, ImageInfo, ImagePruneReport, LogEntry, LogStream, Metrics, MetricsStream, Sandbox, SandboxInfo, SandboxStopResult, Snapshot, SnapshotInfo, SnapshotVerifyReport, Volume, VolumeInfo

Constant Summary collapse

VERSION =

Gem version. Tracks the upstream microsandbox runtime (currently ‘v0.5.7`, the pinned core-crate tag); the patch segment advances for gem-only revisions that add bindings atop the same core. Must equal the native ext’s Cargo crate version (‘Native.version`), enforced by spec/unit/version_spec.rb.

"0.5.8"

Class Method Summary collapse

Class Method Details

.all_sandbox_metrics ⇒ Hash{String => Metrics}

Latest resource-usage snapshot for every running sandbox, keyed by name. Mirrors the official ‘all_sandbox_metrics`/`allSandboxMetrics` helpers.

Returns:



106
107
108
 
# File 'lib/microsandbox.rb', line 106

def all_sandbox_metrics
  Native.all_sandbox_metrics.transform_values { |m| Metrics.new(m) }
end

.ensure_runtime! ⇒ nil

Ensure the ‘msb` runtime + `libkrunfw` are present, provisioning them on first use if not. Called automatically by Microsandbox::Sandbox.create/Microsandbox::Sandbox.start so precompiled-gem users (who never ran the source build) get a working runtime without a manual install step.

The download is attempted at most once per process. Opt out by setting ‘MICROSANDBOX_NO_AUTO_INSTALL` (e.g. air-gapped hosts that provision the runtime out of band); the subsequent operation then surfaces the missing runtime itself. Already-installed runtimes (e.g. source builds) skip straight through with only a cheap presence check.

Returns:

  • (nil) 


75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/microsandbox.rb', line 75

def ensure_runtime!
  return if @runtime_ready
  if installed?
    @runtime_ready = true
    return
  end
  return if auto_install_disabled?

  warn "[microsandbox] runtime (msb + libkrunfw) not found; " \
       "downloading to ~/.microsandbox (set MICROSANDBOX_NO_AUTO_INSTALL to skip)..."
  install
  @runtime_ready = true
  nil
end

.install ⇒ nil

Download and install the ‘msb` runtime + `libkrunfw` into `~/.microsandbox` (idempotent).

When the gem is built from source, the native extension provisions the runtime at build time, so this is usually a no-op. Precompiled platform gems (which skip the local Rust build) do NOT provision it that way, so the runtime is fetched on first use — see ensure_runtime!. Call this explicitly to provision ahead of time (e.g. while baking a container image) so the first Microsandbox::Sandbox.create doesn’t pay the download.

Returns:

  • (nil) 


54
55
56
57
 
# File 'lib/microsandbox.rb', line 54

def install
  Native.install
  nil
end

.installed? ⇒ Boolean

Returns whether the runtime is installed and resolvable.

Returns:

  • (Boolean) —

    whether the runtime is installed and resolvable



60
61
62
 
# File 'lib/microsandbox.rb', line 60

def installed?
  Native.installed?
end

.runtime_path ⇒ String

Returns the resolved path to the ‘msb` runtime binary.

Returns:

  • (String) —

    the resolved path to the ‘msb` runtime binary



91
92
93
 
# File 'lib/microsandbox.rb', line 91

def runtime_path
  Native.resolved_msb_path
end

.runtime_path=(path) ⇒ void

This method returns an undefined value.

Override the ‘msb` runtime path (highest-priority SDK tier of the resolver, below only the `MSB_PATH` environment variable).

Parameters:

  • path (String) 


99
100
101
 
# File 'lib/microsandbox.rb', line 99

def runtime_path=(path)
  Native.set_runtime_msb_path(path.to_s)
end

.version ⇒ String

Returns the gem version.

Returns:

  • (String) —

    the gem version



40
41
42
 
# File 'lib/microsandbox.rb', line 40

def version
  VERSION
end