bsdkrun 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3cc7fd1dcbcb90243855217c4fe7852f6e98baf235fc6e0875ca3f7aeafeb7b
+  data.tar.gz: 92aaa16edb2d6970912f64840835dbd78611cf9f30bc4c5830c1c4f0f537fa71
+SHA512:
+  metadata.gz: 1505af9b58a1397e6de294f06d76b2a8ca81ae0a46ba80f61c12baa6e5de99d8e9fba3c973bee7157c663233e575468bbe175e435fe23a01258855a4278a00fa
+  data.tar.gz: 38b533ac4692529528ce0c5c5739b1f62f8012f7ec6a2ac2814f866c99d7ec47a13ab26f1639e102012ca4e8161483cfe0731c8d987c23432da42133dfc61167

data/README.md

@@ -0,0 +1,218 @@
+# bsdkrun (Ruby SDK)
+
+A Ruby SDK for [**bsdkrun**](https://github.com/tsirysndr/bsdkrun) — a
+Firecracker-style microVM launcher for **BSD and Linux** guests on macOS and
+Linux, built on [libkrun](https://github.com/containers/libkrun). Boot and drive
+microVMs programmatically, inspired by the **Vercel** and **Deno** Sandbox SDKs.
+
+The SDK shells out to the `bsdkrun` binary, so it has **zero runtime
+dependencies** — just the Ruby standard library (`open3`, `json`, `pathname`).
+
+```ruby
+require "bsdkrun"
+
+box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+
+# exec argv directly, with env / stdin / a PTY / a working dir:
+puts box.exec(["uname", "-a"]).text
+box.exec(["apk", "add", "curl"], throw_on_error: true)
+box.run_command("curl", ["-fsSL", "https://example.com"])
+
+box.stop
+```
+
+## Install
+
+```sh
+gem install bsdkrun
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "bsdkrun"
+```
+
+### The `bsdkrun` binary
+
+You need the `bsdkrun` binary itself. The SDK finds it via, in order:
+
+1. `Bsdkrun.binary_path = "/path/to/bsdkrun"`
+2. the `BSDKRUN_BIN` environment variable
+3. `bsdkrun` on your `PATH`
+4. an in-repo `target/release/bsdkrun` or `target/debug/bsdkrun` build
+
+See the [bsdkrun README](../../README.md) for installing the binary (Homebrew on
+macOS, or build from source on Linux/KVM). This SDK assumes libkrun is already
+linked — it does not auto-provision it.
+
+## Creating a sandbox
+
+`Sandbox.create` is discriminated on `os:` — the options change per guest kind.
+Pass keyword arguments or a Hash.
+
+```ruby
+# Linux OCI image (docker run-style)
+Bsdkrun::Sandbox.create(
+  os: "linux",
+  image: "ghcr.io/owner/name:tag",
+  cpus: 2,
+  mem: 1024,
+  volume: "web",                       # persistent CoW rootfs
+  mounts: ["~/project:/src", "~/data:/data:ro"],
+  net: { ports: ["8080:80", "2222:22"] },
+  command: ["node", "server.js"]       # args after `--`
+)
+
+# FreeBSD (EFI on macOS, PVH on Linux/amd64)
+Bsdkrun::Sandbox.create(os: "freebsd", version: "14.3", mem: 2048)
+
+# NetBSD (direct-kernel boot everywhere)
+Bsdkrun::Sandbox.create(os: "netbsd", version: "10.1", volume: "db")
+
+# Boot a raw disk through its UEFI loader
+Bsdkrun::Sandbox.create(os: "firmware", firmware: "KRUN_EFI.fd", disk: "disk.raw")
+
+# Boot a kernel directly, no bootloader
+Bsdkrun::Sandbox.create(os: "kernel", kernel: "netbsd", format: "elf", disk: "root.raw")
+```
+
+Every `create` runs the machine **detached** and returns a `Sandbox` handle.
+
+## Running commands
+
+`exec` is the primary programmatic entrypoint. No shell parsing — pass an argv
+array (or a program name plus `args:`).
+
+```ruby
+box.exec(["ls", "-la", "/etc"])
+
+box.exec("ruby",
+  args: ["-e", "puts ENV['X']"],
+  env: { "X" => "hi" },
+  cwd: "/app",
+  stdin: "data on stdin",
+  tty: true,                 # allocate a PTY
+  throw_on_error: true)      # raise on non-zero exit (default: false)
+
+# Vercel-Sandbox-style alias:
+result = box.run_command("uname", ["-a"])
+result.stdout       # raw stdout
+result.text         # stdout, trailing newlines trimmed
+result.exit_code
+result.ok?          # true on exit 0
+result.lines        # non-empty stdout lines
+```
+
+`exec` returns a `Bsdkrun::Result`. It only raises `CommandFailed` when you pass
+`throw_on_error: true` (or call `result.throw_if_failed!`).
+
+## Lifecycle & inventory
+
+```ruby
+box  = Bsdkrun::Sandbox.create(os: "linux", image: "alpine", command: ["sleep", "300"])
+same = Bsdkrun::Sandbox.get(box.id)          # reconnect (prefix ok)
+all  = Bsdkrun::Sandbox.list(all: true)      # Array<SandboxInfo>
+
+box.status        # SandboxInfo | nil
+box.running?      # true / false
+box.logs          # console log (String)
+box.shell         # interactive shell (inherits the terminal)
+box.stop          # BSD guests clean-poweroff; Linux SIGTERM
+box.start         # restart in place — resumes its own disk/rootfs (data persists)
+box.update(cpus: 4, mem: 2048)               # applies on next start
+box.remove(force: true)
+```
+
+Host-level namespaces:
+
+```ruby
+Bsdkrun::System.probe                          # toolchain sanity check -> Boolean
+Bsdkrun::Images.list                           # Array<ImageInfo>
+Bsdkrun::Volumes.list                          # Array<VolumeInfo>
+Bsdkrun::Volumes.remove("web", force: true)
+Bsdkrun::Networks.list                         # Array<NetworkInfo>
+Bsdkrun::System.fetch_image("freebsd", version: "14.3")
+Bsdkrun::System.versions("netbsd")             # Array<String>
+```
+
+## Networking, SSH & Tailscale
+
+```ruby
+# forward ports at create time
+Bsdkrun::Sandbox.create(os: "linux", image: "alpine", net: { ports: ["2222:22"] })
+
+# agent-managed key-based SSH
+box.ssh_setup                                  # install local ~/.ssh/*.pub keys
+box.ssh_setup(user: "tsiry", key: "~/.ssh/work.pub")
+
+# put a guest on your tailnet
+box.tailscale_up(authkey: "tskey-auth-...", hostname: "web")
+```
+
+### Global networks — reach machines by name
+
+Opt machines into a **shared network** so they get distinct IPs on one subnet
+and reach each other **by IP and by name** (docker-compose style), with internal
+DNS:
+
+```ruby
+require "bsdkrun"
+
+Bsdkrun::Networks.create("devnet")
+
+db = Bsdkrun::Sandbox.create(
+  os: "linux", image: "alpine", name: "db",
+  net: { network: "devnet" }, command: ["sleep", "3600"]
+)
+api = Bsdkrun::Sandbox.create(
+  os: "linux", image: "alpine", name: "api",
+  net: { network: "devnet" }, command: ["sleep", "3600"]
+)
+
+# api reaches db by name over the shared subnet
+api.exec(["ping", "-c1", "db"], throw_on_error: true)
+
+# inspect + manage
+Bsdkrun::Networks.list                # Array<NetworkInfo>
+Bsdkrun::Networks.members("devnet")   # Array<SandboxInfo> on the network
+info = db.status                      # info.network == "devnet", info.net_ip set
+
+# edit membership (applies on next start — a VM's NIC is fixed at boot)
+api.connect_network("devnet")         # or Bsdkrun::Networks.connect(api.id, "devnet")
+api.disconnect_network
+api.start                             # re-joins with the new membership
+
+Bsdkrun::Networks.sync("devnet")      # refresh members' /etc/hosts (fixes NetBSD name lookup)
+Bsdkrun::Networks.remove("devnet", force: true)
+```
+
+Names resolve on Linux and FreeBSD via the network's DNS; **NetBSD** resolves
+via a synced `/etc/hosts` block — joins auto-sync, and `Networks.sync` refreshes
+an existing network without restarting members.
+
+## Errors
+
+All errors extend `Bsdkrun::Error`:
+
+- `Bsdkrun::BinaryNotFound` — the `bsdkrun` binary wasn't found.
+- `Bsdkrun::CommandFailed` — a command exited non-zero (carries `exit_code`,
+  `stdout`, `stderr`, `command`). Raised by `exec` with `throw_on_error: true`,
+  by the lifecycle/namespace helpers, and by the agent helpers.
+- `Bsdkrun::SandboxNotFound` — `Sandbox.get` matched no machine.
+
+## Try it interactively
+
+```sh
+bin/console
+```
+
+Starts IRB with the SDK preloaded — `Bsdkrun::Sandbox`, the `Bsdkrun.images` /
+`.volumes` / `.networks` / `.system` namespaces, plus `ps` (every machine,
+exited ones included) and `last` (the newest one). Pass
+`--bin ../../target/release/bsdkrun` to drive a locally built binary for the
+session.
+
+## License
+
+MIT

data/lib/bsdkrun/args.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # Builds the +bsdkrun+ argv (minus the binary and global flags) for a detached
+  # +create+. Every path ends with +-d+ so +create+ yields a handle.
+  #
+  # Options are a Hash with Symbol keys mirroring the TypeScript SDK's
+  # +CreateOptions+, discriminated on +:os+.
+  module Args
+    module_function
+
+    # Networking flags shared by every guest kind.
+    # @param net [Hash, nil]
+    # @return [Array<String>]
+    def net_args(net)
+      a = []
+      return a unless net
+
+      a.push("--no-net") if net[:disabled]
+      Array(net[:ports]).each do |p|
+        a.push("--port", p.is_a?(String) ? p : "#{p[:host]}:#{p[:guest]}")
+      end
+      a.push("--mac", net[:mac]) if net[:mac]
+      a.push("--network", net[:network]) if net[:network]
+      a
+    end
+
+    # +--name+ flag if a name is set.
+    # @param o [Hash]
+    # @return [Array<String>]
+    def name_args(o)
+      o[:name] ? ["--name", o[:name].to_s] : []
+    end
+
+    # +--cpus+ / +--mem+ sizing flags.
+    # @param o [Hash]
+    # @return [Array<String>]
+    def vm_args(o)
+      a = []
+      a.push("--cpus", o[:cpus].to_s) unless o[:cpus].nil?
+      a.push("--mem", o[:mem].to_s) unless o[:mem].nil?
+      a
+    end
+
+    # Disk-persistence flags shared by BSD / firmware / kernel guests.
+    # @param o [Hash]
+    # @return [Array<String>]
+    def disk_args(o)
+      a = []
+      a.push("--persist") if o[:persist]
+      a.push("-v", o[:volume]) if o[:volume]
+      Array(o[:attach_disk]).each { |d| a.push("--attach-disk", d) }
+      a
+    end
+
+    # Build the full detached +create+ argv for the given options.
+    #
+    # @param opts [Hash] create options, discriminated on +:os+.
+    # @return [Array<String>]
+    # @raise [ArgumentError] on an unknown +:os+.
+    def build_create_args(opts)
+      case opts[:os].to_s
+      when "linux"    then linux_args(opts)
+      when "freebsd"  then freebsd_args(opts)
+      when "netbsd"   then netbsd_args(opts)
+      when "firmware" then firmware_args(opts)
+      when "kernel"   then kernel_args(opts)
+      else raise ArgumentError, "unknown os: #{opts[:os].inspect}"
+      end
+    end
+
+    # @!visibility private
+    def linux_args(opts)
+      a = ["linux", opts.fetch(:image).to_s, "-d"]
+      a.push("--kernel", opts[:kernel]) if opts[:kernel]
+      a.push("--kernel-version", opts[:kernel_version]) if opts[:kernel_version]
+      a.push("--initramfs") if opts[:initramfs]
+      a.push("-v", opts[:volume]) if opts[:volume]
+      Array(opts[:mounts]).each { |m| a.push("--mount", m) }
+      a.push("--entrypoint", opts[:entrypoint]) if opts[:entrypoint]
+      a.push("--console", opts[:console]) if opts[:console]
+      a.concat(net_args(opts[:net])).concat(name_args(opts)).concat(vm_args(opts))
+      cmd = opts[:command]
+      a.push("--", *cmd) if cmd && !cmd.empty?
+      a
+    end
+
+    # @!visibility private
+    def freebsd_args(opts)
+      a = ["freebsd", "-d"]
+      a.push("--version", opts[:version].to_s) if opts[:version]
+      a.push("--firmware", opts[:firmware]) if opts[:firmware]
+      a.push("--force") if opts[:force]
+      a.concat(disk_args(opts)).concat(net_args(opts[:net]))
+       .concat(name_args(opts)).concat(vm_args(opts))
+    end
+
+    # @!visibility private
+    def netbsd_args(opts)
+      a = ["netbsd", "-d"]
+      a.push("--version", opts[:version].to_s) if opts[:version]
+      a.push("--force") if opts[:force]
+      a.concat(disk_args(opts)).concat(net_args(opts[:net]))
+       .concat(name_args(opts)).concat(vm_args(opts))
+    end
+
+    # @!visibility private
+    def firmware_args(opts)
+      a = ["firmware", "--firmware", opts.fetch(:firmware), "--disk", opts.fetch(:disk), "-d"]
+      a.concat(disk_args(opts)).concat(net_args(opts[:net]))
+       .concat(name_args(opts)).concat(vm_args(opts))
+    end
+
+    # @!visibility private
+    def kernel_args(opts)
+      a = ["kernel", "--kernel", opts.fetch(:kernel), "-d"]
+      a.push("--format", opts[:format].to_s) if opts[:format]
+      a.push("--initramfs", opts[:initramfs]) if opts[:initramfs]
+      a.push("--cmdline", opts[:cmdline]) if opts[:cmdline]
+      a.push("--disk", opts[:disk]) if opts[:disk]
+      a.concat(disk_args(opts)).concat(net_args(opts[:net]))
+       .concat(name_args(opts)).concat(vm_args(opts))
+    end
+  end
+end

data/lib/bsdkrun/binary.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Bsdkrun
+  # Locates the +bsdkrun+ binary on the host and caches the result.
+  #
+  # Resolution order (first match wins):
+  #   1. an explicit override set via {Bsdkrun.binary_path=}
+  #   2. the +BSDKRUN_BIN+ environment variable
+  #   3. +bsdkrun+ on +PATH+
+  #   4. an in-repo dev build: +<repo>/target/release/bsdkrun+ then +debug+
+  module Binary
+    @override = nil
+    @resolved = nil
+
+    class << self
+      # Force the SDK to use a specific +bsdkrun+ binary, bypassing discovery.
+      #
+      # @param path [String, nil]
+      # @return [void]
+      def override=(path)
+        @override = path
+        @resolved = nil
+      end
+
+      # @return [String, nil] the current explicit override, if any.
+      attr_reader :override
+
+      # Reset cached discovery state (mainly for tests).
+      # @return [void]
+      def reset!
+        @resolved = nil
+        @override = nil
+      end
+
+      # Resolve (and cache) the path to the +bsdkrun+ binary.
+      #
+      # @return [String] the resolved absolute path or bare command name.
+      # @raise [BinaryNotFound] when nothing matched.
+      def resolve
+        return @resolved if @resolved
+
+        searched = candidates
+        searched.each do |candidate|
+          if path_like?(candidate)
+            return @resolved = candidate if File.exist?(candidate)
+          else
+            found = which(candidate)
+            return @resolved = found if found
+          end
+        end
+        raise BinaryNotFound, searched
+      end
+
+      private
+
+      def path_like?(candidate)
+        candidate.include?(File::SEPARATOR) ||
+          (File::ALT_SEPARATOR && candidate.include?(File::ALT_SEPARATOR))
+      end
+
+      # Candidate locations, in priority order.
+      def candidates
+        out = []
+        out << @override if @override
+
+        env = ENV["BSDKRUN_BIN"]
+        out << env if env && !env.empty?
+
+        # A `bsdkrun` already on PATH wins over in-repo builds.
+        on_path = which("bsdkrun")
+        out << on_path if on_path
+
+        # This file lives at sdk/ruby/lib/bsdkrun/binary.rb, so the repo root is
+        # four levels up. Prefer a release build, fall back to debug.
+        repo_root = File.expand_path("../../../..", __dir__)
+        out << File.join(repo_root, "target", "release", "bsdkrun")
+        out << File.join(repo_root, "target", "debug", "bsdkrun")
+        out
+      end
+
+      # Cross-platform PATH lookup for an executable.
+      def which(name)
+        exts =
+          if File::ALT_SEPARATOR
+            (ENV["PATHEXT"] || ".EXE;.CMD;.BAT").split(";")
+          else
+            [""]
+          end
+        (ENV["PATH"] || "").split(File::PATH_SEPARATOR).each do |dir|
+          next if dir.empty?
+
+          exts.each do |ext|
+            full = File.join(dir, name + ext)
+            return full if File.file?(full) && File.executable?(full)
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/bsdkrun/errors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # Base class for every error the SDK raises.
+  class Error < StandardError; end
+
+  # The +bsdkrun+ binary could not be located on the host.
+  class BinaryNotFound < Error
+    # @param searched [Array<String>] the paths that were probed, in order.
+    def initialize(searched)
+      super(
+        'could not find the "bsdkrun" binary. Set BSDKRUN_BIN, add it to PATH, ' \
+        "or set Bsdkrun.binary_path=. Looked in: #{Array(searched).join(', ')}"
+      )
+    end
+  end
+
+  # A +bsdkrun+ invocation exited non-zero.
+  class CommandFailed < Error
+    # @return [Integer] the process exit status.
+    attr_reader :exit_code
+    # @return [String] the captured standard output.
+    attr_reader :stdout
+    # @return [String] the captured standard error.
+    attr_reader :stderr
+    # @return [String] a human label for the command that failed.
+    attr_reader :command
+
+    # @param exit_code [Integer]
+    # @param stdout [String]
+    # @param stderr [String]
+    # @param command [String] label describing the invocation.
+    def initialize(exit_code:, stdout:, stderr:, command:)
+      @exit_code = exit_code
+      @stdout = stdout
+      @stderr = stderr
+      @command = command
+      message = "command failed (exit #{exit_code}): #{command}"
+      trimmed = stderr.to_s.strip
+      message += "\n#{trimmed}" unless trimmed.empty?
+      super(message)
+    end
+  end
+
+  # No machine matched the given id / prefix.
+  class SandboxNotFound < Error
+    # @param id [String] the id or prefix that matched nothing.
+    def initialize(id)
+      super("no sandbox found matching id #{id.inspect}")
+    end
+  end
+end

data/lib/bsdkrun/images.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bsdkrun
+  # Host-level image operations.
+  module Images
+    module_function
+
+    # List downloaded images (pulled OCI images + fetched BSD images).
+    # @return [Array<ImageInfo>]
+    def list
+      res = Process.run!(["images", "--json"], label: "bsdkrun images")
+      rows = JSON.parse(res.stdout.empty? ? "[]" : res.stdout)
+      rows.map { |row| ImageInfo.from_row(row) }
+    end
+  end
+end

data/lib/bsdkrun/networks.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bsdkrun
+  # Global-network operations — shared subnets where members reach each other by
+  # IP and by name.
+  module Networks
+    module_function
+
+    # List global networks and their member counts.
+    # @return [Array<NetworkInfo>]
+    def list
+      res = Process.run!(["network", "ls", "--json"], label: "bsdkrun network ls")
+      rows = JSON.parse(res.stdout.empty? ? "[]" : res.stdout)
+      rows.map { |row| NetworkInfo.from_row(row) }
+    end
+
+    # Create a global network (starts its shared switch).
+    # @param name [String]
+    # @return [void]
+    def create(name)
+      Process.run!(["network", "create", name], label: "bsdkrun network create")
+      nil
+    end
+
+    # Remove one or more networks. +force+ allows removal with running members.
+    # @param names [String, Array<String>]
+    # @param force [Boolean]
+    # @return [void]
+    def remove(names, force: false)
+      args = ["network", "rm"]
+      args << "--force" if force
+      args.concat(Array(names))
+      Process.run!(args, label: "bsdkrun network rm")
+      nil
+    end
+
+    # Join or switch a machine to a network. Applies on the machine's next start.
+    # @param machine [String] id or name.
+    # @param network [String]
+    # @return [void]
+    def connect(machine, network)
+      Process.run!(["network", "connect", machine, network], label: "bsdkrun network connect")
+      nil
+    end
+
+    # Detach a machine from its network. Applies on its next start.
+    # @param machine [String]
+    # @return [void]
+    def disconnect(machine)
+      Process.run!(["network", "disconnect", machine], label: "bsdkrun network disconnect")
+      nil
+    end
+
+    # Refresh members' +/etc/hosts+ so peers resolve by name (notably NetBSD).
+    # @param network [String]
+    # @return [void]
+    def sync(network)
+      Process.run!(["network", "sync", network], label: "bsdkrun network sync")
+      nil
+    end
+
+    # The machines currently attached to +network+ (running or stopped).
+    # @param network [String]
+    # @return [Array<SandboxInfo>]
+    def members(network)
+      Sandbox.list(all: true).select { |m| m.network == network }
+    end
+  end
+end

data/lib/bsdkrun/process.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Bsdkrun
+  # Spawns the +bsdkrun+ CLI and captures its output.
+  #
+  # Every invocation is prefixed with +--log-level+ (default 0) so the SDK's
+  # captured output stays clean.
+  module Process
+    # Captured output of a raw CLI invocation.
+    #
+    # @!attribute [r] stdout
+    #   @return [String]
+    # @!attribute [r] stderr
+    #   @return [String]
+    # @!attribute [r] exit_code
+    #   @return [Integer]
+    RawResult = Struct.new(:stdout, :stderr, :exit_code, keyword_init: true)
+
+    module_function
+
+    # Run +bsdkrun --log-level <n> <args>+ to completion, buffering output.
+    #
+    # @param args [Array<String>] CLI arguments (without the binary).
+    # @param env [Hash] extra environment merged onto the process env.
+    # @param stdin [String, nil] data piped to the child's stdin.
+    # @param log_level [Integer] bsdkrun global log level (0=off .. 5=trace).
+    # @return [RawResult]
+    def run(args, env: {}, stdin: nil, log_level: 0)
+      bin = Binary.resolve
+      full = ["--log-level", log_level.to_s, *args]
+      merged_env = env.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+      out, err, status = Open3.capture3(merged_env, bin, *full, stdin_data: stdin || "")
+      RawResult.new(stdout: out, stderr: err, exit_code: status.exitstatus || 0)
+    end
+
+    # Run and raise {CommandFailed} on a non-zero exit.
+    #
+    # @param args [Array<String>]
+    # @param label [String] human label used in the error.
+    # @return [RawResult]
+    # @raise [CommandFailed]
+    def run!(args, label:, **opts)
+      res = run(args, **opts)
+      unless res.exit_code.zero?
+        raise CommandFailed.new(
+          exit_code: res.exit_code, stdout: res.stdout, stderr: res.stderr, command: label
+        )
+      end
+      res
+    end
+
+    # Spawn an interactive +bsdkrun+ command inheriting the parent's stdio and
+    # wait for it (for +shell+). Returns the child's exit status boolean.
+    #
+    # @param args [Array<String>]
+    # @param log_level [Integer]
+    # @return [Boolean] true if the command exited zero.
+    def spawn_interactive(args, log_level: 0)
+      bin = Binary.resolve
+      full = ["--log-level", log_level.to_s, *args]
+      system(bin, *full)
+    end
+  end
+end

data/lib/bsdkrun/sandbox.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bsdkrun
+  # A handle to a running (or stopped) bsdkrun microVM.
+  #
+  # Create one with {Sandbox.create}, reconnect with {Sandbox.get}, or enumerate
+  # with {Sandbox.list}.
+  #
+  # @example
+  #   box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+  #   box.exec(["uname", "-a"]).text
+  #   box.stop
+  class Sandbox
+    ID_RE = /\A[0-9a-f]{6,}\z/
+    SSH_PORT_RE = /ssh -p (\d+)/
+    private_constant :ID_RE, :SSH_PORT_RE
+
+    # The machine's Docker-style short id.
+    # @return [String]
+    attr_reader :id
+
+    # Host port forwarded to the guest's SSH, if the boot banner reported one.
+    # @return [Integer, nil]
+    attr_reader :ssh_port
+
+    # @param id [String]
+    # @param ssh_port [Integer, nil]
+    def initialize(id, ssh_port: nil)
+      @id = id
+      @ssh_port = ssh_port
+    end
+
+    class << self
+      # Boot a new microVM and return a handle to it.
+      #
+      # Accepts create options as a keyword list or a Hash; discriminated on
+      # +:os+ ("linux", "freebsd", "netbsd", "firmware", "kernel").
+      #
+      # @param opts [Hash]
+      # @return [Sandbox]
+      # @raise [CommandFailed] if boot fails or no machine id is printed.
+      def create(opts = {}, **kwargs)
+        opts = normalize(opts.merge(kwargs))
+        args = Args.build_create_args(opts)
+        res = Process.run(args, log_level: opts.fetch(:log_level, 1))
+        if res.exit_code != 0
+          raise CommandFailed.new(
+            exit_code: res.exit_code, stdout: res.stdout, stderr: res.stderr,
+            command: "bsdkrun create"
+          )
+        end
+        # Detached runs print just the machine id on stdout.
+        id = res.stdout.split("\n").map(&:strip).select { |l| l.match?(ID_RE) }.last
+        unless id
+          raise CommandFailed.new(
+            exit_code: res.exit_code, stdout: res.stdout, stderr: res.stderr,
+            command: "bsdkrun create (no machine id in output)"
+          )
+        end
+        match = res.stderr.match(SSH_PORT_RE)
+        new(id, ssh_port: match && match[1].to_i)
+      end
+
+      # Reconnect to an existing machine by id (a unique prefix is enough).
+      #
+      # @param id [String]
+      # @return [Sandbox]
+      # @raise [SandboxNotFound]
+      def get(id)
+        row = list(all: true).find { |m| m.id == id || m.id.start_with?(id) }
+        raise SandboxNotFound, id unless row
+
+        new(row.id)
+      end
+
+      # List machines. +all: true+ includes exited ones (default running only).
+      #
+      # @param all [Boolean]
+      # @return [Array<SandboxInfo>]
+      def list(all: false)
+        args = ["ps", "--json"]
+        args << "--all" if all
+        res = Process.run!(args, label: "bsdkrun ps")
+        rows = JSON.parse(res.stdout.empty? ? "[]" : res.stdout)
+        rows.map { |row| SandboxInfo.from_row(row) }
+      end
+
+      # Symbolize keys and normalize a nested +:net+ hash.
+      # @!visibility private
+      def normalize(opts)
+        h = opts.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+        h[:net] = h[:net].each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v } if h[:net].is_a?(Hash)
+        h
+      end
+    end
+
+    # Run a command in the guest through its exec agent.
+    #
+    # +command+ may be an Array (argv, no shell parsing) or a String program
+    # name; with a String, +args:+ supplies its arguments.
+    #
+    # @param command [String, Array<String>]
+    # @param args [Array<String>] arguments when +command+ is a bare String.
+    # @param env [Hash] environment variables (+-e K=V+).
+    # @param tty [Boolean] allocate a pseudo-TTY in the guest (+-t+).
+    # @param stdin [String, nil] data piped to the command's stdin.
+    # @param cwd [String, nil] working directory (emulated via +sh -c 'cd …'+).
+    # @param throw_on_error [Boolean] raise {CommandFailed} on a non-zero exit.
+    # @param log_level [Integer] per-command bsdkrun log level.
+    # @return [Result]
+    def exec(command, args: [], env: {}, tty: false, stdin: nil, cwd: nil,
+             throw_on_error: false, log_level: 0)
+      argv = command.is_a?(Array) ? command.dup : [command, *args]
+
+      if cwd
+        # Emulate a working directory: cd, drop it, then exec the real argv.
+        argv = ["/bin/sh", "-c", 'cd "$1" && shift && exec "$@"', "sh", cwd, *argv]
+      end
+
+      cli = ["exec"]
+      cli << "-t" if tty
+      env.each { |k, v| cli.push("-e", "#{k}=#{v}") }
+      cli.push(@id, *argv)
+
+      res = Process.run(cli, stdin: stdin, log_level: log_level)
+      result = Result.new(
+        stdout: res.stdout, stderr: res.stderr, exit_code: res.exit_code,
+        command: "exec #{argv.join(' ')}"
+      )
+      result.throw_if_failed! if throw_on_error
+      result
+    end
+
+    # Vercel-Sandbox-style alias for {#exec}: a program plus its args.
+    #
+    # @param command [String]
+    # @param args [Array<String>]
+    # @return [Result]
+    def run_command(command, args = [], **opts)
+      exec(command, args: args, **opts)
+    end
+
+    # Read the machine's console log.
+    #
+    # @param boot [Boolean] show bsdkrun's own boot log instead of the console.
+    # @return [String]
+    def logs(boot: false)
+      args = ["logs"]
+      args << "--boot" if boot
+      args << @id
+      Process.run(args).stdout
+    end
+
+    # Attach an interactive shell to the machine (inherits the terminal).
+    # @return [Boolean] true if the shell exited zero.
+    def shell
+      Process.spawn_interactive(["shell", @id])
+    end
+
+    # Fetch this machine's current status row, or nil if it's gone.
+    # @return [SandboxInfo, nil]
+    def status
+      Sandbox.list(all: true).find { |m| m.id == @id }
+    end
+
+    # Whether the machine is currently running.
+    # @return [Boolean]
+    def running?
+      s = status
+      s ? s.running : false
+    end
+
+    # Stop the machine. BSD guests are cleanly powered off; Linux is SIGTERM'd.
+    # @return [void]
+    def stop
+      lifecycle(["stop", @id], "bsdkrun stop")
+    end
+
+    # Restart a stopped machine in place (same id, disk/rootfs). Boots detached.
+    # @return [void]
+    def start
+      lifecycle(["start", @id], "bsdkrun start")
+    end
+
+    # Remove the machine and its state. +force+ stops it first if running.
+    # @param force [Boolean]
+    # @return [void]
+    def remove(force: false)
+      args = ["rm"]
+      args << "--force" if force
+      args << @id
+      lifecycle(args, "bsdkrun rm")
+    end
+
+    # Change the recorded vCPU / RAM. Applies on the next {#start}.
+    # @param cpus [Integer, nil]
+    # @param mem [Integer, nil]
+    # @return [void]
+    def update(cpus: nil, mem: nil)
+      args = ["update", @id]
+      args.push("--cpus", cpus.to_s) unless cpus.nil?
+      args.push("--mem", mem.to_s) unless mem.nil?
+      lifecycle(args, "bsdkrun update")
+    end
+
+    # Join or switch this machine to a global network. Applies on next {#start}.
+    # @param network [String]
+    # @return [void]
+    def connect_network(network)
+      lifecycle(["network", "connect", @id, network], "bsdkrun network connect")
+    end
+
+    # Detach this machine from its network. Applies on next {#start}.
+    # @return [void]
+    def disconnect_network
+      lifecycle(["network", "disconnect", @id], "bsdkrun network disconnect")
+    end
+
+    # Install SSH keys in the guest via the agent (+ssh setup+). With no keys,
+    # the CLI installs your local +~/.ssh/*.pub+.
+    #
+    # @param user [String, nil] target user (default root).
+    # @param key [String, Array<String>, nil] literal key(s) or +.pub+ path(s).
+    # @return [Result]
+    def ssh_setup(user: nil, key: nil)
+      action = ["setup"]
+      action.push("--user", user) if user
+      Array(key).each { |k| action.push("--key", k) }
+      agent("ssh", action)
+    end
+
+    # Put the guest on your tailnet (+tailscale setup+).
+    #
+    # @param authkey [String, nil] tailnet auth key (sent as +TS_AUTHKEY+).
+    # @param hostname [String, nil] machine name on the tailnet.
+    # @param args [Array<String>] extra args passed through to +tailscale up+.
+    # @return [Result]
+    def tailscale_up(authkey: nil, hostname: nil, args: [])
+      action = ["setup"]
+      action.push("--hostname", hostname) if hostname
+      action.concat(args)
+      agent("tailscale", action, env: authkey ? { "TS_AUTHKEY" => authkey } : {})
+    end
+
+    private
+
+    # Run a fire-and-forget lifecycle CLI command, raising on failure.
+    def lifecycle(args, label)
+      Process.run!(args, label: label)
+      nil
+    end
+
+    # Run an in-guest agent CLI family (+ssh+, +tailscale+), raising on failure.
+    def agent(family, action, env: {})
+      res = Process.run([family, @id, *action], env: env)
+      result = Result.new(
+        stdout: res.stdout, stderr: res.stderr, exit_code: res.exit_code,
+        command: "#{family} #{action.join(' ')}"
+      )
+      result.throw_if_failed!
+    end
+  end
+end

data/lib/bsdkrun/system.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # Host-level toolchain / image operations.
+  module System
+    module_function
+
+    # Sanity-check the toolchain: verify libkrun links and a context can be
+    # created/configured. Does not boot.
+    # @return [Boolean] true on success.
+    def probe
+      Process.run(["probe"]).exit_code.zero?
+    end
+
+    # Download + prepare a BSD image ahead of time.
+    #
+    # @param os [String] "freebsd" or "netbsd".
+    # @param version [String, nil]
+    # @param force [Boolean] re-download even if cached.
+    # @return [String] the command output.
+    def fetch_image(os, version: nil, force: false)
+      args = ["fetch", "--os", os.to_s]
+      args.push("--version", version.to_s) if version
+      args << "--force" if force
+      Process.run!(args, label: "bsdkrun fetch").stdout
+    end
+
+    # List the builds available to fetch for a BSD, one version per line.
+    #
+    # @param os [String] "freebsd" or "netbsd".
+    # @return [Array<String>] version strings (non-empty output lines).
+    def versions(os)
+      res = Process.run!(["versions", "--os", os.to_s], label: "bsdkrun versions")
+      res.stdout.split("\n").map(&:strip).reject(&:empty?)
+    end
+
+    # Grow a raw disk image (the guest expands its root FS on next boot).
+    #
+    # @param disk [String]
+    # @param size [String]
+    # @return [void]
+    def grow_disk(disk, size)
+      Process.run!(["grow", "--disk", disk, "--size", size], label: "bsdkrun grow")
+      nil
+    end
+  end
+end

data/lib/bsdkrun/types.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # A machine as reported by +bsdkrun ps --json+.
+  #
+  # @!attribute [r] id
+  #   @return [String]
+  # @!attribute [r] name
+  #   @return [String, nil] DNS name on a network, or nil if unnamed.
+  # @!attribute [r] status
+  #   @return [String] "running" or "exited" (derived from +running+).
+  SandboxInfo = Data.define(
+    :id, :name, :image, :kind, :command, :status, :running, :exit_code,
+    :pid, :detached, :cpus, :mem, :volume, :state_dir, :network, :net_ip,
+    :created_at, :finished_at
+  ) do
+    # Map a +ps --json+ row (String keys) to a typed instance.
+    # @param row [Hash]
+    # @return [SandboxInfo]
+    def self.from_row(row)
+      running = !!row["running"]
+      new(
+        id: row["id"].to_s,
+        name: row["name"],
+        image: row["image"].to_s,
+        kind: row["kind"].to_s,
+        command: (row["command"] || "").to_s,
+        status: running ? "running" : "exited",
+        running: running,
+        exit_code: to_i_or_nil(row["exit_code"]),
+        pid: to_i_or_nil(row["pid"]),
+        detached: !!row["detached"],
+        cpus: row["cpus"].to_i,
+        mem: row["mem"].to_i,
+        volume: row["volume"],
+        state_dir: row["state_dir"].to_s,
+        network: row["network"],
+        net_ip: row["net_ip"],
+        created_at: row["created_at"].to_i,
+        finished_at: to_i_or_nil(row["finished_at"])
+      )
+    end
+
+    def self.to_i_or_nil(value)
+      value.nil? ? nil : value.to_i
+    end
+  end
+
+  # An image as reported by +bsdkrun images --json+.
+  ImageInfo = Data.define(:id, :reference, :digest, :size, :rootfs, :created_at) do
+    # @param row [Hash]
+    # @return [ImageInfo]
+    def self.from_row(row)
+      new(
+        id: row["id"].to_s,
+        reference: row["reference"].to_s,
+        digest: row["digest"].to_s,
+        size: row["size"].to_i,
+        rootfs: row["rootfs"].to_s,
+        created_at: row["created_at"].to_i
+      )
+    end
+  end
+
+  # A volume as reported by +bsdkrun volume ls --json+.
+  VolumeInfo = Data.define(:name, :guest, :base, :path, :size, :created_at, :tracked) do
+    # @param row [Hash]
+    # @return [VolumeInfo]
+    def self.from_row(row)
+      created = row["created_at"]
+      new(
+        name: row["name"].to_s,
+        guest: row["guest"],
+        base: row["base"],
+        path: row["path"].to_s,
+        size: row["size"].to_s,
+        created_at: created.nil? ? nil : created.to_i,
+        tracked: !!row["tracked"]
+      )
+    end
+  end
+
+  # A global network as reported by +bsdkrun network ls --json+.
+  NetworkInfo = Data.define(:name, :subnet, :gateway, :members, :running, :up, :created_at) do
+    # @param row [Hash]
+    # @return [NetworkInfo]
+    def self.from_row(row)
+      created = row["created_at"]
+      new(
+        name: row["name"].to_s,
+        subnet: row["subnet"].to_s,
+        gateway: row["gateway"].to_s,
+        members: (row["members"] || 0).to_i,
+        running: (row["running"] || 0).to_i,
+        up: !!row["up"],
+        created_at: created.nil? ? nil : created.to_i
+      )
+    end
+  end
+
+  # The captured result of running a command in a guest via {Sandbox#exec}.
+  #
+  # @!attribute [r] stdout
+  #   @return [String]
+  # @!attribute [r] stderr
+  #   @return [String]
+  # @!attribute [r] exit_code
+  #   @return [Integer]
+  # @!attribute [r] command
+  #   @return [String] a human label for the command.
+  Result = Data.define(:stdout, :stderr, :exit_code, :command) do
+    # @return [Boolean] whether the command succeeded (exit 0).
+    def ok?
+      exit_code.zero?
+    end
+
+    # @return [String] stdout with trailing newlines trimmed — the common case.
+    def text
+      stdout.sub(/\n+\z/, "")
+    end
+
+    # @return [Object] stdout parsed as JSON.
+    def json
+      require "json"
+      JSON.parse(stdout)
+    end
+
+    # @return [Array<String>] non-empty stdout lines.
+    def lines
+      stdout.split("\n").reject(&:empty?)
+    end
+
+    # @raise [CommandFailed] if the command exited non-zero.
+    # @return [self]
+    def throw_if_failed!
+      unless ok?
+        raise CommandFailed.new(
+          exit_code: exit_code, stdout: stdout, stderr: stderr, command: command
+        )
+      end
+      self
+    end
+  end
+end

data/lib/bsdkrun/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # The bsdkrun Ruby SDK version.
+  VERSION = "0.1.0"
+end

data/lib/bsdkrun/volumes.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bsdkrun
+  # Host-level volume operations.
+  module Volumes
+    module_function
+
+    # List persistent volumes.
+    # @return [Array<VolumeInfo>]
+    def list
+      res = Process.run!(["volume", "ls", "--json"], label: "bsdkrun volume ls")
+      rows = JSON.parse(res.stdout.empty? ? "[]" : res.stdout)
+      rows.map { |row| VolumeInfo.from_row(row) }
+    end
+
+    # Remove one or more volumes (and their data).
+    #
+    # @param names [String, Array<String>]
+    # @param force [Boolean]
+    # @return [void]
+    def remove(names, force: false)
+      args = ["volume", "rm"]
+      args << "--force" if force
+      args.concat(Array(names))
+      Process.run!(args, label: "bsdkrun volume rm")
+      nil
+    end
+  end
+end

data/lib/bsdkrun.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "bsdkrun/version"
+require_relative "bsdkrun/errors"
+require_relative "bsdkrun/binary"
+require_relative "bsdkrun/process"
+require_relative "bsdkrun/args"
+require_relative "bsdkrun/types"
+require_relative "bsdkrun/sandbox"
+require_relative "bsdkrun/images"
+require_relative "bsdkrun/volumes"
+require_relative "bsdkrun/networks"
+require_relative "bsdkrun/system"
+
+# bsdkrun — a Ruby SDK for {https://github.com/tsirysndr/bsdkrun bsdkrun}, a
+# Firecracker-style microVM launcher for BSD and Linux guests. A thin wrapper
+# around the +bsdkrun+ CLI: it builds argv, shells out, and parses JSON output.
+#
+# @example
+#   require "bsdkrun"
+#
+#   box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+#   puts box.exec(["uname", "-a"]).text
+#   box.stop
+module Bsdkrun
+  class << self
+    # Force the SDK to use a specific +bsdkrun+ binary, bypassing discovery.
+    # @param path [String, nil]
+    # @return [void]
+    def binary_path=(path)
+      Binary.override = path
+    end
+
+    # @return [String] the resolved +bsdkrun+ binary path.
+    # @raise [BinaryNotFound]
+    def binary_path
+      Binary.resolve
+    end
+
+    # Reset cached binary discovery state (mainly for tests).
+    # @return [void]
+    def reset_binary!
+      Binary.reset!
+    end
+
+    # Convenience alias for {Sandbox.create}.
+    # @return [Sandbox]
+    def create(opts = {}, **kwargs)
+      Sandbox.create(opts, **kwargs)
+    end
+
+    # Convenience alias for {Sandbox.get}.
+    # @return [Sandbox]
+    def get(id)
+      Sandbox.get(id)
+    end
+
+    # Convenience alias for {Sandbox.list}.
+    # @return [Array<SandboxInfo>]
+    def list(all: false)
+      Sandbox.list(all: all)
+    end
+
+    # The {Images} namespace.
+    # @return [Module]
+    def images
+      Images
+    end
+
+    # The {Volumes} namespace.
+    # @return [Module]
+    def volumes
+      Volumes
+    end
+
+    # The {Networks} namespace.
+    # @return [Module]
+    def networks
+      Networks
+    end
+
+    # The {System} namespace.
+    # @return [Module]
+    def system
+      System
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: bsdkrun
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tsiry Sandratraina
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  A thin, dependency-free Ruby wrapper around the `bsdkrun` CLI. Boot and drive
+  BSD/Linux microVMs programmatically: create sandboxes, exec commands, manage
+  lifecycle, and wire up global networks, volumes and images.
+email:
+- tsiry.sndr@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/bsdkrun.rb
+- lib/bsdkrun/args.rb
+- lib/bsdkrun/binary.rb
+- lib/bsdkrun/errors.rb
+- lib/bsdkrun/images.rb
+- lib/bsdkrun/networks.rb
+- lib/bsdkrun/process.rb
+- lib/bsdkrun/sandbox.rb
+- lib/bsdkrun/system.rb
+- lib/bsdkrun/types.rb
+- lib/bsdkrun/version.rb
+- lib/bsdkrun/volumes.rb
+homepage: https://github.com/tsirysndr/bsdkrun
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tsirysndr/bsdkrun
+  source_code_uri: https://github.com/tsirysndr/bsdkrun/tree/main/sdk/ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby SDK for bsdkrun — a Firecracker-style microVM launcher for BSD and Linux
+  guests.
+test_files: []