Class: Microsandbox::Sandbox

Inherits:
Object
  • Object
show all
Defined in:
lib/microsandbox/sandbox.rb

Overview

A running sandbox (microVM) — the primary entry point of the SDK.

Examples:

Block form (auto-stops on exit)

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

Manual lifecycle

sb = Microsandbox::Sandbox.create("hello", image: "python")
begin
  sb.shell("echo hi")
ensure
  sb.stop
end

Constant Summary collapse

DISK_IMAGE_EXTENSIONS =

Recognized disk-image rootfs extensions, mirroring the upstream DiskImageFormat::from_extension/FromStr set. Used by disk_image_rootfs? to gate the fstype:-vs-OCI check; keep in sync on a runtime-tag bump.

%w[raw qcow2 vmdk].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(native) ⇒ Sandbox

Returns a new instance of Sandbox.



1195
1196
1197
 
# File 'lib/microsandbox/sandbox.rb', line 1195

def initialize(native)
  @native = native
end

Class Method Details

.build_create_opts(image: nil, cpus: nil, max_cpus: nil, memory: nil, max_memory: nil, env: nil, workdir: nil, shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil, entrypoint: nil, cmd: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil, dns: nil, tls: nil, ipv4_pool: nil, ipv6_pool: nil, max_connections: nil, trust_host_cas: nil, rate_limiter: nil, vsock: nil, patches: nil, from_snapshot: nil, fstype: nil, init: nil, ephemeral: false, log_level: nil, quiet_logs: false, security: nil, root_disk: nil, oci_upper_size: nil, max_duration: nil, idle_timeout: nil, rlimits: nil, pull_policy: nil, registry_auth: nil, registry_insecure: false, registry_ca_certs: nil, secrets: nil, on_secret_violation: nil, detached: false, replace: false, replace_with_timeout: nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Shared keyword-option builder for create/create_with_progress.



439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
 
# File 'lib/microsandbox/sandbox.rb', line 439

def build_create_opts(image: nil, cpus: nil, max_cpus: nil, memory: nil, max_memory: nil,
  env: nil, workdir: nil,
  shell: nil, user: nil, hostname: nil, labels: nil, scripts: nil,
  entrypoint: nil, cmd: nil, ports: nil, ports_udp: nil, volumes: nil, network: nil,
  dns: nil, tls: nil, ipv4_pool: nil, ipv6_pool: nil,
  max_connections: nil, trust_host_cas: nil, rate_limiter: nil, vsock: nil,
  patches: nil,
  from_snapshot: nil, fstype: nil, init: nil, ephemeral: false,
  log_level: nil, quiet_logs: false, security: nil,
  root_disk: nil, oci_upper_size: nil, max_duration: nil, idle_timeout: nil, rlimits: nil,
  pull_policy: nil, registry_auth: nil, registry_insecure: false,
  registry_ca_certs: nil, secrets: nil, on_secret_violation: nil,
  detached: false, replace: false, replace_with_timeout: nil)
  # A sandbox boots from exactly one rootfs source. The core would reject a
  # contradictory pair, but only after a runtime round-trip; fail fast and
  # clearly here (the Python SDK validates this the same way).
  if image && from_snapshot
    raise ArgumentError, "provide either image: or from_snapshot:, not both"
  end
  if root_disk && oci_upper_size
    raise ArgumentError, "pass either root_disk: or oci_upper_size:, not both"
  end
  Microsandbox.ensure_runtime!
  # `fstype:` names the inner filesystem of a disk-image rootfs, so it only
  # applies when `image:` is a disk-image path (a local path ending in
  # .raw/.qcow2/.vmdk). Routing an OCI ref (e.g. "python") through the
  # disk-image builder would make the core treat it as a host disk path and
  # fail at boot, so reject the combination up front instead of forwarding a
  # value the native layer can't honour.
  if fstype && !disk_image_rootfs?(image)
    raise ArgumentError,
      "fstype: only applies to a disk-image rootfs; image: must be a local " \
      "path ending in .raw, .qcow2, or .vmdk (got #{image.inspect}). " \
      "OCI references auto-detect their filesystem — drop fstype:."
  end
  opts = {}
  opts["image"] = image.to_s if image
  opts["from_snapshot"] = from_snapshot.to_s if from_snapshot
  opts["fstype"] = fstype.to_s if fstype
  opts["cpus"] = Integer(cpus) if cpus
  opts["max_cpus"] = Integer(max_cpus) if max_cpus
  opts["memory"] = Integer(memory) if memory
  opts["max_memory"] = Integer(max_memory) if max_memory
  opts["workdir"] = workdir.to_s if workdir
  opts["shell"] = shell.to_s if shell
  opts["user"] = user.to_s if user
  opts["hostname"] = hostname.to_s if hostname
  opts["env"] = stringify(env) if env
  opts["labels"] = stringify(labels) if labels
  opts["scripts"] = stringify(scripts) if scripts
  # entrypoint/cmd: an explicit empty Array clears the image's value
  # (blocking the image-config merge), so presence is keyed on the kwarg
  # itself — nil (the default) inherits from the image.
  opts["entrypoint"] = Array(entrypoint).map(&:to_s) unless entrypoint.nil?
  opts["cmd"] = Array(cmd).map(&:to_s) unless cmd.nil?
  opts["ports"] = intify_ports(ports) if ports
  opts["ports_udp"] = intify_ports(ports_udp) if ports_udp
  opts["volumes"] = normalize_volumes(volumes) if volumes
  opts["patches"] = normalize_patches(patches) if patches
  apply_network_opts(opts, network) unless network.nil?
  opts["dns"] = normalize_dns(dns) if dns
  opts["tls"] = normalize_tls(tls) if tls
  opts["ipv4_pool"] = ipv4_pool.to_s if ipv4_pool
  opts["ipv6_pool"] = ipv6_pool.to_s if ipv6_pool
  opts["max_connections"] = Integer(max_connections) if max_connections
  set_bool(opts, "trust_host_cas", trust_host_cas)
  opts["rate_limiter"] = normalize_rate_limiter(rate_limiter) if rate_limiter
  opts["vsock"] = normalize_vsock(vsock) if vsock
  opts["log_level"] = log_level.to_s if log_level
  opts["quiet_logs"] = true if quiet_logs
  opts["security"] = security.to_s if security
  if oci_upper_size
    warn "Microsandbox: oci_upper_size: is deprecated; use root_disk: " \
         "(an Integer size in MiB, or RootDisk.managed/tmpfs/disk)",
      uplevel: 2
    opts["root_disk"] = coerce_root_disk_size(oci_upper_size, "oci_upper_size:")
  elsif root_disk
    opts["root_disk"] = normalize_root_disk(root_disk)
  end
  opts["max_duration"] = Integer(max_duration) if max_duration
  opts["idle_timeout"] = Integer(idle_timeout) if idle_timeout
  opts["rlimits"] = normalize_rlimits(rlimits) if rlimits
  opts["pull_policy"] = pull_policy.to_s if pull_policy
  apply_registry_opts(opts, registry_auth, registry_insecure, registry_ca_certs)
  opts["secrets"] = normalize_secrets(secrets) if secrets
  opts["on_secret_violation"] = normalize_violation(on_secret_violation) if on_secret_violation
  opts["init"] = normalize_init(init) unless init.nil?
  opts["ephemeral"] = true if ephemeral
  opts["detached"] = true if detached
  if replace_with_timeout
    opts["replace_with_timeout"] = coerce_duration(replace_with_timeout, "replace_with_timeout")
  elsif replace
    opts["replace"] = true
  end

  opts
end

.create(name, **kwargs) {|sandbox| ... } ⇒ Sandbox, Object

Create and boot a sandbox.

When a block is given the sandbox is yielded and stopped automatically when the block returns (the block's value is returned); otherwise the live Microsandbox::Sandbox is returned and you are responsible for calling #stop.

Parameters:

  • name (String) —

    sandbox name (max 128 UTF-8 bytes)

  • image (String, nil) —

    OCI image reference (e.g. "python")

  • cpus (Integer, nil) —

    number of vCPUs

  • max_cpus (Integer, nil) —

    boot-time maximum vCPU ceiling a later live #modify can grow up to (defaults to cpus; must be >= cpus)

  • memory (Integer, nil) —

    memory in MiB

  • max_memory (Integer, nil) —

    boot-time maximum memory ceiling (MiB) a later live #modify can grow up to (defaults to memory; must be >= memory)

  • env (Hash, nil) —

    environment variables

  • workdir (String, nil) —

    working directory inside the guest

  • shell (String, nil) —

    default shell (for #shell)

  • user (String, nil) —

    default user

  • hostname (String, nil) —

    guest hostname

  • labels (Hash, nil) —

    metadata labels

  • scripts (Hash, nil) —

    named scripts to install

  • entrypoint (Array<String>, nil) —

    image ENTRYPOINT override. An explicit [] clears the image's ENTRYPOINT (so exec_default runs the CMD alone); nil (the default) inherits it.

  • cmd (Array<String>, nil) —

    image CMD override used by default-workload execution (#exec_default et al., runtime v0.6.9). Durable configuration — it does not execute anything at create time (create boots the VM only). An explicit [] clears the image CMD; nil (the default) inherits it.

  • ports (Hash, nil) —

    host_port => guest_port TCP publications

  • ports_udp (Hash, nil) —

    host_port => guest_port UDP publications

  • volumes (Hash, nil) —

    guest_path => mount spec. Each value is a host path String (a bind mount), or a Hash: { bind: "/host" }, { named: "vol" }, { tmpfs: true, size_mib: 64 }, or { disk: "/img.raw", format: "raw", fstype: "ext4" }. Any mount may add flags ro:/readonly:, noexec:, nosuid:, nodev:, and (bind/named only) stat_virtualization: (:strict/:relaxed/:off) and host_permissions: (:private/:mirror). A bind mount accepts quota_mib: to override the runtime's default guest-write budget (4 GiB as of v0.5.10); the core rejects it on tmpfs/disk/named (for a named volume, set its quota via Volume.create). Bind/named mounts also accept follow_root_symlinks: true to opt out of the default-on mount-root symlink protection (runtime v0.6.7).

  • network (Array, String, Symbol, NetworkPolicy, Hash, nil) —

    network policy. Composable profiles ([:public] (the default), [:public, :private], :host, …), a terminal preset (:none, :allow_all), a NetworkPolicy (e.g. NetworkPolicy.from_profiles, NetworkPolicy.custom), or a Hash describing a custom policy (profiles:, default_egress:, default_ingress:, rules:, deny_domains:, deny_domain_suffixes:). See NetworkPolicy and Rule. The v0.6.6 public_only/non_local presets were removed in runtime v0.6.7 — use [:public] / [:public, :private].

  • dns (Hash, nil) —

    custom DNS: { nameservers: [...], rebind_protection: true, query_timeout_ms: 2000 }

  • tls (Hash, nil) —

    TLS-interception tuning: { bypass: [...patterns], verify_upstream: true, intercepted_ports: [443, 8443], block_quic: true, upstream_ca_cert:, intercept_ca_cert:, intercept_ca_key: } (paths). Use this to inject secrets: on non-443 ports or to trust a private CA.

  • ipv4_pool (String, nil) —

    guest IPv4 address pool CIDR (e.g. "10.0.0.0/24")

  • ipv6_pool (String, nil) —

    guest IPv6 address pool CIDR

  • max_connections (Integer, nil) —

    cap on concurrent proxied connections

  • trust_host_cas (Boolean, nil) —

    trust the host's CA bundle for upstream TLS

  • rate_limiter (Hash, nil) —

    per-sandbox egress/ingress token-bucket limits (runtime v0.6.9, local backend): { egress: { bandwidth: { size: 1_048_576, refill_time_ms: 1000, one_time_burst: 0 }, ops: { size: 1000, refill_time_ms: 1000 } }, ingress: { ... } }. bandwidth buckets meter bytes, ops buckets meter network frames; an omitted bucket or direction is unlimited.

  • vsock (Hash, Array, nil) —

    host sockets exposed on guest-to-host vsock ports (runtime v0.6.9): { "/host/api.sock" => 5000 } (stream sockets), or an Array of { host_socket:, port:, socket_type: :stream|:dgram } Hashes. Guests connect to host CID 2 on the given port; no in-guest proxy required.

  • from_snapshot (String, nil) —

    boot from a snapshot name or digest instead of an image (mutually exclusive with image:)

  • fstype (String, nil) —

    inner filesystem type (e.g. "ext4") when image: is a disk-image rootfs path whose filesystem can't be auto-probed; ignored for OCI images

  • init (String, Hash, nil) —

    hand guest PID 1 to an init system: a command path (e.g. "/lib/systemd/systemd" or "auto"), or a Hash { cmd:, args:, env: } when the init binary takes argv/extra env

  • ephemeral (Boolean) —

    auto-remove the sandbox's stored state (DB row, disk, logs, captured output) once it reaches a terminal state (default: state is persisted until remove)

  • patches (Array<Hash>, nil) —

    rootfs patches applied before boot, each built with the Patch factory (e.g. Patch.text(...), Patch.mkdir(...)). Not compatible with disk-image roots.

  • log_level ("error", "warn", "info", "debug", "trace", nil) —

    guest log verbosity

  • quiet_logs (Boolean) —

    suppress sandbox process logs

  • security ("default", "restricted", nil) —

    exec security profile

  • root_disk (Integer, Hash, nil) —

    the OCI sandbox's writable root disk (runtime v0.6.7). An Integer is the managed ext4 upper's size cap in MiB (default kind, 4 GiB when unset); a Hash picks a kind via the RootDisk factory — RootDisk.managed(8192), RootDisk.tmpfs(2048) (RAM-backed, pristine on every boot), RootDisk.disk("./scratch.img", format: "raw", fstype: "ext4") (user-supplied image attached writable), or RootDisk.flat(8192, clone: :auto) (a single complete ext4 root disk materialized from the OCI image, runtime v0.6.9 — skips the overlay stack; content-addressed and cached across sandboxes).

  • oci_upper_size (Integer, nil) —

    deprecated alias for root_disk: <Integer> (the managed kind); warns, and conflicts with root_disk:

  • max_duration (Integer, nil) —

    hard wall-clock lifetime, in seconds

  • idle_timeout (Integer, nil) —

    stop after this many idle seconds

  • rlimits (Hash, nil) —

    resource limits: { resource => limit } or { resource => [soft, hard] } (e.g. { nofile: 65_535 })

  • pull_policy ("always", "if-missing", "never", nil) —

    image pull behavior

  • registry_auth (Hash, nil) —

    credentials for a private/authenticated registry: { username:, password: } (the password may be a token). Without this the core's default resolution chain still applies (OS keyring, global config, ~/.docker/config.json).

  • registry_insecure (Boolean) —

    reach the registry over plain HTTP instead of HTTPS (for local/self-hosted registries)

  • registry_ca_certs (String, Array<String>, nil) —

    extra PEM-encoded CA root certificate(s) to trust (for a registry with a private CA)

  • secrets (Array<Hash>, nil) —

    placeholder-protected secrets injected by the TLS proxy (auto-enables TLS interception). Each Hash needs env: and value: plus an allow list — host: (single), hosts: (Array), and/or host_patterns: (wildcards like "*.stripe.com"). Optional per-secret: placeholder:, require_tls:, injection toggles inject_headers: / inject_basic_auth: / inject_query: / inject_body:, and on_violation:.

  • on_secret_violation (String, Symbol, Hash, nil) —

    sandbox-wide secret-leak policy: "block", "block_and_log", "block_and_terminate", "passthrough" (passthrough-all-hosts), or a Hash { passthrough_hosts:, passthrough_host_patterns:, passthrough_all_hosts: }

  • detached (Boolean) —

    keep running after this process exits

  • replace (Boolean) —

    replace an existing sandbox with the same name

  • replace_with_timeout (Numeric, nil) —

    replace, waiting up to N seconds

Yield Parameters:

Returns:

  • (Sandbox, Object) —

    the sandbox, or the block's return value



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/microsandbox/sandbox.rb', line 401

def create(name, **kwargs, &block)
  opts = build_create_opts(**kwargs)
  sandbox = new(Native::Sandbox.create(name.to_s, opts))
  return sandbox unless block_given?

  begin
    yield sandbox
  ensure
    begin
      sandbox.stop
    rescue Microsandbox::Error
      # best-effort cleanup; ignore stop failures during teardown
    end
  end
end

.create_with_progress(name, **kwargs) ⇒ PullSession

Create a sandbox while streaming image-pull progress. Accepts the same options as create; returns a PullSession — iterate it (an Enumerable of progress-event Hashes, each with a "kind"), then call PullSession#sandbox for the booted Microsandbox::Sandbox. Mirrors the Python create_with_progress / Node createWithPullProgress.

Returns:



423
424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/microsandbox/sandbox.rb', line 423

def create_with_progress(name, **kwargs)
  # Unlike {create}, this has no block form: the booted sandbox is reached
  # via {PullSession#sandbox} (after iterating progress) and stopped by the
  # caller. A block would be silently dropped — and the sandbox leaked — so
  # reject it loudly rather than let a `create`-style block call misfire.
  if block_given?
    raise ArgumentError,
      "create_with_progress takes no block; iterate the returned PullSession " \
      "for progress, then call #sandbox and stop it when done"
  end
  opts = build_create_opts(**kwargs)
  PullSession.new(Native::Sandbox.create_with_progress(name.to_s, opts))
end

.get(name) ⇒ SandboxHandle

Fetch a controllable handle for a sandbox by name (running or not).

Returns:



546
547
548
 
# File 'lib/microsandbox/sandbox.rb', line 546

def get(name)
  SandboxHandle.new(Native::Sandbox.get(name.to_s))
end

.list ⇒ SandboxPage

List the first page of sandboxes (default page size 20) as controllable handles. Cursor-paginated as of runtime v0.6.8 — follow Microsandbox::SandboxPage#next_cursor via list_with for subsequent pages.

Returns:



554
555
556
 
# File 'lib/microsandbox/sandbox.rb', line 554

def list
  build_page(Native::Sandbox.list)
end

.list_with(labels: {}, limit: nil, cursor: nil) ⇒ SandboxPage

List one configured page of sandboxes.

Parameters:

  • labels (Hash) (defaults to: {}) —

    required key => value labels (AND-matched)

  • limit (Integer, nil) (defaults to: nil) —

    page size, 1..100 (upstream default 20)

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

    opaque cursor from a previous page's Microsandbox::SandboxPage#next_cursor

Returns:



564
565
566
567
568
569
 
# File 'lib/microsandbox/sandbox.rb', line 564

def list_with(labels: {}, limit: nil, cursor: nil)
  opts = {"labels" => stringify(labels)}
  opts["limit"] = Integer(limit) if limit
  opts["cursor"] = cursor.to_s if cursor
  build_page(Native::Sandbox.list_with(opts))
end

.remove(name) ⇒ nil

Remove a (stopped) sandbox by name.

Returns:

  • (nil) 


573
574
575
576
 
# File 'lib/microsandbox/sandbox.rb', line 573

def remove(name)
  Native::Sandbox.remove(name.to_s)
  nil
end

.start(name, detached: false) ⇒ Sandbox

Restart a previously-defined sandbox by name.

Returns:



539
540
541
542
 
# File 'lib/microsandbox/sandbox.rb', line 539

def start(name, detached: false)
  Microsandbox.ensure_runtime!
  new(Native::Sandbox.start(name.to_s, {"detached" => detached}))
end

Instance Method Details

#attach(command, args = [], cwd: nil, user: nil, env: nil, detach_keys: nil, rlimits: nil) ⇒ Integer

Attach an interactive terminal to a command in the sandbox.

Puts the host terminal into raw mode and forwards keystrokes (and SIGWINCH resizes) to the guest until the command exits or the detach sequence is typed. Requires a real TTY on stdin/stdout, so it is for CLI use, not library/automation code (use #exec/#exec_stream there). Blocks until the session ends. Mirrors the official SDKs' attach.

Parameters:

  • command (String) —

    the program to run

  • args (Array<String>) (defaults to: []) —

    its arguments

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

    working directory

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

    user to run as

  • env (Hash, nil) (defaults to: nil) —

    extra environment variables

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

    detach sequence (e.g. "ctrl-p,ctrl-q"; default "ctrl-]")

  • rlimits (Hash, nil) (defaults to: nil) —

    resource limits (see #exec)

Returns:

  • (Integer) —

    the command's exit code (or the code at detach)



1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
 
# File 'lib/microsandbox/sandbox.rb', line 1302

def attach(command, args = [], cwd: nil, user: nil, env: nil, detach_keys: nil, rlimits: nil)
  opts = {}
  opts["cwd"] = cwd.to_s if cwd
  opts["user"] = user.to_s if user
  opts["env"] = env.each_with_object({}) { |(k, v), a| a[k.to_s] = v.to_s } if env
  opts["detach_keys"] = detach_keys.to_s if detach_keys
  if rlimits
    opts["rlimits"] = rlimits.map do |resource, limit|
      soft, hard = limit.is_a?(Array) ? [limit[0], limit[1]] : [limit, limit]
      [resource.to_s, Integer(soft), Integer(hard)]
    end
  end
  @native.attach(command.to_s, Array(args).map(&:to_s), opts)
end

#attach_default(cwd: nil, user: nil, env: nil, detach_keys: nil, rlimits: nil) ⇒ Integer

Attach an interactive terminal to the image's resolved OCI ENTRYPOINT and CMD — the default workload (runtime v0.6.9). See #attach for the host-TTY requirements and #exec_default for default-workload semantics.

Parameters:

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

    working directory

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

    user to run as

  • env (Hash, nil) (defaults to: nil) —

    extra environment variables

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

    detach sequence (default "ctrl-]")

  • rlimits (Hash, nil) (defaults to: nil) —

    resource limits (see #exec)

Returns:

  • (Integer) —

    the workload's exit code (or the code at detach)

Raises:

  • (NoDefaultCommandError) —

    when no executable default command resolves



1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
 
# File 'lib/microsandbox/sandbox.rb', line 1335

def attach_default(cwd: nil, user: nil, env: nil, detach_keys: nil, rlimits: nil)
  opts = {}
  opts["cwd"] = cwd.to_s if cwd
  opts["user"] = user.to_s if user
  opts["env"] = env.each_with_object({}) { |(k, v), a| a[k.to_s] = v.to_s } if env
  opts["detach_keys"] = detach_keys.to_s if detach_keys
  if rlimits
    opts["rlimits"] = rlimits.map do |resource, limit|
      soft, hard = limit.is_a?(Array) ? [limit[0], limit[1]] : [limit, limit]
      [resource.to_s, Integer(soft), Integer(hard)]
    end
  end
  @native.attach_default(opts)
end

#attach_shell ⇒ Integer

Attach an interactive terminal running the sandbox's default shell. See #attach for the host-TTY requirements.

Returns:

  • (Integer) —

    the shell's exit code (or the code at detach)



1320
1321
1322
 
# File 'lib/microsandbox/sandbox.rb', line 1320

def attach_shell
  @native.attach_shell
end

#detach ⇒ nil

Detach this handle: disarm the stop-on-drop safety net so the sandbox keeps running after this handle is gone (and after this process exits).

Returns:

  • (nil) 


1539
1540
1541
1542
 
# File 'lib/microsandbox/sandbox.rb', line 1539

def detach
  @native.detach
  nil
end

#drain ⇒ nil

Trigger a graceful drain (SIGUSR1).

Returns:

  • (nil) 


1512
1513
1514
1515
 
# File 'lib/microsandbox/sandbox.rb', line 1512

def drain
  @native.drain
  nil
end

#exec(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil) ⇒ ExecOutput

Run a command (no shell interpretation) and collect its output.

Parameters:

  • command (String) —

    the executable

  • args (Array<String>) (defaults to: []) —

    arguments

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

    working directory

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

    user to run as

  • env (Hash, nil) (defaults to: nil) —

    extra environment variables

  • timeout (Numeric, nil) (defaults to: nil) —

    kill the command after N seconds and raise ExecTimeoutError. Omit or pass nil for no timeout. Note the asymmetry: 0 is not "disable" — it is an immediate (zero) deadline, so the command is killed before producing any output and ExecTimeoutError is raised. Use +nil+/omit, never 0, to mean "no limit".

  • tty (Boolean) (defaults to: false) —

    allocate a pseudo-terminal

  • stdin (String, Symbol, nil) (defaults to: nil) —

    bytes to feed to stdin, or :pipe to open a streaming stdin pipe (write/close it via ExecHandle#stdin; only useful with the streaming variants)

Returns:



1221
1222
1223
1224
 
# File 'lib/microsandbox/sandbox.rb', line 1221

def exec(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
  ExecOutput.new(@native.exec(command.to_s, Array(args).map(&:to_s),
    exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
end

#exec_default(cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil) ⇒ ExecOutput

Run the image's resolved OCI ENTRYPOINT and CMD — the default workload (runtime v0.6.9) — and collect output. create is strictly boot-only, so this is how the image's own command gets executed; override the durable CMD at create time via cmd:.

Options match #exec minus the command itself.

Returns:

Raises:

  • (NoDefaultCommandError) —

    when the image's effective entrypoint and CMD resolve to no executable command



1242
1243
1244
1245
1246
 
# File 'lib/microsandbox/sandbox.rb', line 1242

def exec_default(cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
  ExecOutput.new(@native.exec_default(
    exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)
  ))
end

#exec_default_stream(cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil) ⇒ ExecHandle

Note:

Like #exec_stream, timeout: is accepted but not applied on the streaming path.

Run the default workload (see #exec_default) and stream its output.

Returns:

Raises:

  • (NoDefaultCommandError) —

    when no executable default command resolves



1279
1280
1281
1282
1283
 
# File 'lib/microsandbox/sandbox.rb', line 1279

def exec_default_stream(cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
  ExecHandle.new(@native.exec_default_stream(
    exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: true)
  ))
end

#exec_stream(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil) ⇒ ExecHandle

Note:

timeout: is accepted for signature symmetry with #exec but is not applied on the streaming path (the runtime discards it). Enforce a deadline yourself around the iteration, or use blocking #exec with timeout: for the kill-after-N-seconds behavior.

Run a command and stream its output as it arrives.

Pass stdin: :pipe to feed the process interactively: ExecHandle#stdin then returns a writable sink; close it to send EOF (a process like cat that reads until EOF will otherwise block forever).

Returns:

See Also:



1260
1261
1262
1263
 
# File 'lib/microsandbox/sandbox.rb', line 1260

def exec_stream(command, args = [], cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
  ExecHandle.new(@native.exec_stream(command.to_s, Array(args).map(&:to_s),
    exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: true)))
end

#fs ⇒ FS

Guest filesystem operations.

Returns:



1352
1353
1354
 
# File 'lib/microsandbox/sandbox.rb', line 1352

def fs
  @fs ||= FS.new(@native)
end

#inspect ⇒ Object 



1544
1545
1546
 
# File 'lib/microsandbox/sandbox.rb', line 1544

def inspect
  "#<Microsandbox::Sandbox name=#{name.inspect}>"
end

#kill ⇒ nil

Force-kill the sandbox (SIGKILL).

Returns:

  • (nil) 


1505
1506
1507
1508
 
# File 'lib/microsandbox/sandbox.rb', line 1505

def kill
  @native.kill
  nil
end

#log_stream(sources: nil, since_ms: nil, from_cursor: nil, until_ms: nil, follow: false) ⇒ LogStream

Stream captured logs as they appear.

Parameters:

  • sources (Array<String,Symbol>, nil) (defaults to: nil) —

    filter by source ("stdout"/"stderr"/"output"/"system"/"all")

  • since_ms (Numeric, nil) (defaults to: nil) —

    start at the first entry at/after this Unix ms

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

    resume exactly after a prior LogEntry#cursor (mutually exclusive with since_ms; takes precedence if both given)

  • until_ms (Numeric, nil) (defaults to: nil) —

    stop before any entry at/after this Unix ms

  • follow (Boolean) (defaults to: false) —

    keep the stream open for new entries past current EOF

Returns:



1478
1479
1480
1481
1482
1483
1484
1485
1486
 
# File 'lib/microsandbox/sandbox.rb', line 1478

def log_stream(sources: nil, since_ms: nil, from_cursor: nil, until_ms: nil, follow: false)
  opts = {}
  opts["sources"] = Array(sources).map(&:to_s) if sources
  opts["since_ms"] = Float(since_ms) if since_ms
  opts["from_cursor"] = from_cursor.to_s if from_cursor
  opts["until_ms"] = Float(until_ms) if until_ms
  opts["follow"] = true if follow
  LogStream.new(@native.log_stream(opts))
end

#logs(tail: nil, since_ms: nil, until_ms: nil, sources: nil) ⇒ Array<LogEntry>

Read captured logs.

Parameters:

  • tail (Integer, nil) (defaults to: nil) —

    only the last N entries

  • since_ms (Numeric, nil) (defaults to: nil) —

    only entries at/after this Unix ms

  • until_ms (Numeric, nil) (defaults to: nil) —

    only entries before this Unix ms

  • sources (Array<String,Symbol>, nil) (defaults to: nil) —

    filter by source ("stdout"/"stderr"/"output"/"system"/"all")

Returns:



1443
1444
1445
1446
1447
1448
1449
1450
 
# File 'lib/microsandbox/sandbox.rb', line 1443

def logs(tail: nil, since_ms: nil, until_ms: nil, sources: nil)
  opts = {}
  opts["tail"] = Integer(tail) if tail
  opts["since_ms"] = Float(since_ms) if since_ms
  opts["until_ms"] = Float(until_ms) if until_ms
  opts["sources"] = Array(sources).map(&:to_s) if sources
  @native.logs(opts).map { |entry| LogEntry.new(entry) }
end

#metrics ⇒ Metrics

Latest resource-usage snapshot.

Raises a Error ("sandbox N has no live metrics slot") when called in the brief window right after create returns, before the runtime has registered the sandbox's metrics slot. On v0.6.x runtimes the spawn handshake no longer blocks create until the first sample is written, so the slot goes live a beat after boot (within a few hundred milliseconds); retry for that window rather than treating the first failure as fatal.

Returns:



1375
1376
1377
 
# File 'lib/microsandbox/sandbox.rb', line 1375

def metrics
  Metrics.new(@native.metrics)
end

#metrics_stream(interval: 1.0) ⇒ MetricsStream

Stream resource-usage snapshots, one per interval tick, until the sandbox stops. Requires metrics to be enabled for the sandbox.

The first tick fires immediately, so opening the stream right after create can hit the same metrics-slot startup window as #metrics and yield a transient "no live metrics slot" error on that first tick. Because the stream is single-pass (a drained or errored stream is spent), make sure the slot is live before opening it — e.g. retry #metrics until it succeeds (the slot goes live within a few hundred milliseconds of boot), then call #metrics_stream.

Parameters:

  • interval (Numeric) (defaults to: 1.0) —

    seconds between snapshots

Returns:



1464
1465
1466
 
# File 'lib/microsandbox/sandbox.rb', line 1464

def metrics_stream(interval: 1.0)
  MetricsStream.new(@native.metrics_stream(coerce_duration(interval, "interval")))
end

#modify(**kwargs) ⇒ ModificationPlan

Plan or apply a live modification of this sandbox: resize CPU/memory, adjust env/labels/workdir, and rotate/remove secrets, without recreating the sandbox. The apply is all-or-nothing under the chosen policy:: the default :no_restart applies only changes that are live-capable right now and raises if any requested change needs a restart (on a running sandbox that includes env/labels/workdir and adding a secret — rotating or removing an existing one is live). Pass policy: :next_start to persist restart-required changes for the next start, or :restart to restart and apply them now; use dry_run: true to preview each change's disposition without applying anything. Mirrors the official SDKs' modify. Returns a ModificationPlan classifying each change.

Parameters:

  • cpus (Integer, nil) —

    desired effective vCPU count

  • max_cpus (Integer, nil) —

    desired boot-time maximum vCPU ceiling

  • memory (Integer, nil) —

    desired effective guest memory in MiB

  • max_memory (Integer, nil) —

    desired boot-time maximum memory (MiB)

  • root_disk_size (Integer, nil) —

    desired root-disk size in MiB (runtime v0.6.9): grows the sandbox-owned managed upper or flat root disk. Growth-only, applied while the sandbox is stopped — restart/next-start semantics and backing-specific limits are enforced by the runtime

  • env (Hash, nil) —

    environment variables to set for future execs

  • remove_env (Array<String>, nil) —

    environment variable names to remove

  • labels (Hash, nil) —

    labels to set

  • remove_labels (Array<String>, nil) —

    label keys to remove

  • workdir (String, nil) —

    desired working directory for future execs

  • secrets (Hash, nil) —

    desired secret specs keyed by secret name. Each spec is a Hash with at most one of env: (host env var to read), store: (host secret-store reference), or value: (raw material), plus optional placeholder: and allowed_hosts: (Array of host patterns).

  • remove_secrets (Array<String>, nil) —

    secret names to remove

  • policy (Symbol, String, nil) —

    :no_restart (default — apply only changes that need no restart), :next_start (persist for the next start), or :restart (restart to apply restart-required changes)

  • dry_run (Boolean) —

    compute the plan without applying anything

Returns:



1430
1431
1432
1433
 
# File 'lib/microsandbox/sandbox.rb', line 1430

def modify(**kwargs)
  opts = Sandbox.send(:build_modify_opts, **kwargs)
  ModificationPlan.new(JSON.parse(@native.modify(opts)))
end

#name ⇒ String

Returns the sandbox name.

Returns:

  • (String) —

    the sandbox name



1200
1201
1202
 
# File 'lib/microsandbox/sandbox.rb', line 1200

def name
  @native.name
end

#owns_lifecycle? ⇒ Boolean

Returns whether this handle owns the sandbox process lifecycle (i.e. stopping it or dropping the handle terminates the sandbox).

Returns:

  • (Boolean) —

    whether this handle owns the sandbox process lifecycle (i.e. stopping it or dropping the handle terminates the sandbox)



1532
1533
1534
 
# File 'lib/microsandbox/sandbox.rb', line 1532

def owns_lifecycle?
  @native.owns_lifecycle
end

#ping ⇒ PingResult

Health-check the guest agent without refreshing the idle timer. Sends core.ping to the running sandbox and reports the round-trip latency. Mirrors the official SDKs' ping.

Returns:



1383
1384
1385
 
# File 'lib/microsandbox/sandbox.rb', line 1383

def ping
  PingResult.new(@native.ping)
end

#shell(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil) ⇒ ExecOutput

Run a shell script (pipes, redirects, etc. allowed) and collect output.

Returns:



1228
1229
1230
1231
 
# File 'lib/microsandbox/sandbox.rb', line 1228

def shell(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
  ExecOutput.new(@native.shell(script.to_s,
    exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:)))
end

#shell_stream(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil) ⇒ ExecHandle

Note:

Like #exec_stream, timeout: is accepted but not applied on the streaming path.

Run a shell script and stream its output as it arrives.

Returns:



1269
1270
1271
1272
 
# File 'lib/microsandbox/sandbox.rb', line 1269

def shell_stream(script, cwd: nil, user: nil, env: nil, timeout: nil, tty: false, stdin: nil, rlimits: nil)
  ExecHandle.new(@native.shell_stream(script.to_s,
    exec_opts(cwd:, user:, env:, timeout:, tty:, stdin:, rlimits:, pipe_ok: true)))
end

#ssh ⇒ SshOps

SSH access to the sandbox — open a native in-process SSH client or prepare a reusable server endpoint.

Examples:

sb.ssh.open_client { |c| puts c.exec("hostname").stdout }

Returns:



1361
1362
1363
 
# File 'lib/microsandbox/sandbox.rb', line 1361

def ssh
  SshOps.new(@native)
end

#status ⇒ Symbol

The live status, fetched from the backend (a round-trip per call).

Returns:

  • (Symbol) —

    :created, :starting, :running, :draining, :paused, :stopped, or :crashed



1526
1527
1528
 
# File 'lib/microsandbox/sandbox.rb', line 1526

def status
  @native.status.to_sym
end

#stop ⇒ nil

Gracefully stop the sandbox (SIGTERM→SIGKILL escalation, 10s default) and wait for it to terminate. For a custom timeout or fire-and-return request_* control, fetch a Microsandbox::SandboxHandle via get.

Returns:

  • (nil) 


1492
1493
1494
1495
 
# File 'lib/microsandbox/sandbox.rb', line 1492

def stop
  @native.stop
  nil
end

#stop_and_wait ⇒ ExitStatus

Gracefully stop, then wait for the process to exit.

Returns:



1499
1500
1501
 
# File 'lib/microsandbox/sandbox.rb', line 1499

def stop_and_wait
  ExitStatus.new(@native.stop_and_wait)
end

#touch ⇒ TouchResult

Explicitly refresh this sandbox's idle-activity timer (resetting any idle_timeout: countdown). Mirrors the official SDKs' touch.

Returns:



1390
1391
1392
 
# File 'lib/microsandbox/sandbox.rb', line 1390

def touch
  TouchResult.new(@native.touch)
end

#wait ⇒ ExitStatus

Wait for the sandbox process to exit.

Returns:



1519
1520
1521
 
# File 'lib/microsandbox/sandbox.rb', line 1519

def wait
  ExitStatus.new(@native.wait)
end