Module: Microsandbox

Defined in:
lib/microsandbox.rb,
lib/microsandbox/fs.rb,
lib/microsandbox/ssh.rb,
lib/microsandbox/agent.rb,
lib/microsandbox/image.rb,
lib/microsandbox/patch.rb,
lib/microsandbox/errors.rb,
lib/microsandbox/volume.rb,
lib/microsandbox/metrics.rb,
lib/microsandbox/network.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

Modules: Destination, Patch, Rule Classes: AgentClient, AgentFrame, AgentStream, Error, ExecEvent, ExecHandle, ExecOutput, ExecStdin, ExitStatus, FS, FsEntry, FsMetadata, Image, ImageDetail, ImageInfo, ImagePruneReport, LogEntry, LogStream, Metrics, MetricsStream, NetworkPolicy, Sandbox, SandboxHandle, SandboxStopResult, SftpClient, Snapshot, SnapshotInfo, SnapshotVerifyReport, SshClient, SshOps, SshOutput, SshServer, Volume, VolumeInfo

Constant Summary collapse

SandboxInfo =
Deprecated.

since v0.5.8. Microsandbox::Sandbox.get/Microsandbox::Sandbox.list now return a controllable SandboxHandle; this constant remains as an alias so code that referenced the old read-only metadata type by name (e.g. ‘is_a?` checks) still resolves. Note it is now the same class as SandboxHandle, whose constructor takes a native handle, not the metadata Hash the old `SandboxInfo.new` accepted — construct via Microsandbox::Sandbox.get/Microsandbox::Sandbox.list.

SandboxHandle
VERSION =

Gem version. Versioned independently of the upstream microsandbox runtime it embeds: the gem follows its own semver (while 0.x, breaking changes bump the minor and fixes bump the patch), so the number does NOT track the upstream tag one-to-one. Consult RUNTIME_VERSION for the wrapped runtime, and the Versioning section of the README for the full gem-to-runtime map. Must equal the native ext’s Cargo crate version (‘Native.version`), enforced by spec/unit/version_spec.rb.

"0.6.0"
RUNTIME_VERSION =

The upstream microsandbox runtime release this gem build embeds — the ‘tag` pinned on the `microsandbox`/`microsandbox-network` git deps in ext/microsandbox/Cargo.toml. Exposed at runtime as runtime_version. spec/unit/version_spec.rb asserts it stays in sync with the Cargo tag so it can’t silently drift out of date.

"v0.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:



180
181
182
 
# File 'lib/microsandbox.rb', line 180

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

.default_backend_kind ⇒ Symbol

Returns the active default backend kind, :local or :cloud. The first call resolves the env/profile/config ladder.

Returns:

  • (Symbol) —

    the active default backend kind, :local or :cloud. The first call resolves the env/profile/config ladder.



173
174
175
 
# File 'lib/microsandbox.rb', line 173

def default_backend_kind
  Native.default_backend_kind.to_sym
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) 


88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/microsandbox.rb', line 88

def ensure_runtime!
  return if @runtime_ready
  # A cloud backend has no local msb/libkrunfw runtime to provision: skip the
  # presence check and the first-use download entirely. Resolving the kind
  # uses the same lazy env/profile/config ladder every operation already
  # consults, so this adds no work for local hosts (the common case).
  return if default_backend_kind == :cloud
  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) 


67
68
69
70
 
# File 'lib/microsandbox.rb', line 67

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



73
74
75
 
# File 'lib/microsandbox.rb', line 73

def installed?
  Native.installed?
end

.libkrunfw_path=(path) ⇒ void

This method returns an undefined value.

Override the ‘libkrunfw` shared-library path (SDK tier of the resolver, below the `MSB_LIBKRUNFW_PATH` environment variable). Process-level and set-once: a second call is silently ignored, and the env var still wins. Mirrors runtime_path= for libkrunfw.

Parameters:

  • path (String) 


127
128
129
 
# File 'lib/microsandbox.rb', line 127

def libkrunfw_path=(path)
  Native.set_runtime_libkrunfw_path(path.to_s)
end

.runtime_path ⇒ String

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

Returns:

  • (String) —

    the resolved path to the ‘msb` runtime binary



109
110
111
 
# File 'lib/microsandbox.rb', line 109

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) 


117
118
119
 
# File 'lib/microsandbox.rb', line 117

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

.runtime_version ⇒ String

The upstream microsandbox runtime release this gem build embeds (the git ‘tag` pinned in ext/microsandbox/Cargo.toml). The gem’s own version is versioned independently of this, so consult this to learn which runtime is wrapped. See the Versioning section of the README for the full map.

Returns:

  • (String) —

    e.g. “v0.5.8”



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

def runtime_version
  RUNTIME_VERSION
end

.set_default_backend(kind, url: nil, api_key: nil, profile: nil) ⇒ void

This method returns an undefined value.

Install a process-wide default backend (v0.5.8 backend routing). Without a call to this, operations use a local libkrun backend; the env/profile ladder (‘MSB_BACKEND`, `MSB_API_URL`+`MSB_API_KEY`, `MSB_PROFILE`, `~/.microsandbox/config.json`) is resolved lazily on first use. Call once at startup, before any sandbox operations.

Parameters:

  • kind ("local", "cloud", Symbol) —

    backend kind

  • url (String, nil) (defaults to: nil) —

    cloud control-plane URL (cloud, unless ‘profile:`)

  • api_key (String, nil) (defaults to: nil) —

    cloud API key (cloud, unless ‘profile:`)

  • profile (String, nil) (defaults to: nil) —

    named profile from ‘~/.microsandbox/config.json`



142
143
144
 
# File 'lib/microsandbox.rb', line 142

def set_default_backend(kind, url: nil, api_key: nil, profile: nil)
  Native.set_default_backend(kind.to_s, url&.to_s, api_key&.to_s, profile&.to_s)
end

.version ⇒ String

Returns the gem version.

Returns:

  • (String) —

    the gem version



44
45
46
 
# File 'lib/microsandbox.rb', line 44

def version
  VERSION
end

.with_backend(kind, url: nil, api_key: nil, profile: nil) { ... } ⇒ Object

Run the given block with a temporary default backend, restoring the previous one afterward (even on error). NOTE: the swap is process-wide while the block runs, not fiber/thread-local — concurrent threads observe the temporary backend. It is also NOT safe to call from multiple threads at once: two interleaved ‘with_backend` calls can restore each other’s saved backend out of order and leave a temporary backend installed permanently. Use it only when no other thread is changing the backend, and avoid calling set_default_backend inside the block (the restore on exit would overwrite that change). Mirrors the official SDKs’ scoped-backend helper.

Parameters:

  • kind ("local", "cloud", Symbol)
  • url (String, nil) (defaults to: nil)
  • api_key (String, nil) (defaults to: nil)
  • profile (String, nil) (defaults to: nil)

Yields:

  • with the temporary backend installed

Returns:

  • (Object) —

    the block’s return value



162
163
164
165
166
167
168
169
 
# File 'lib/microsandbox.rb', line 162

def with_backend(kind, url: nil, api_key: nil, profile: nil)
  token = Native.push_default_backend(kind.to_s, url&.to_s, api_key&.to_s, profile&.to_s)
  begin
    yield
  ensure
    Native.pop_default_backend(token)
  end
end