superradcompany/microsandbox

Microsandbox is a cross-platform runtime for creating and managing isolated microVM-based sandboxes, providing a unified API for lifecycle management, resource allocation, and secure execution. It supports OCI image-based root filesystems, persistent storage volumes, and granular network policies including DNS filtering and TLS interception. The system exposes a comprehensive SDK in Rust, Python, TypeScript, Go, and Ruby, enabling developers to programmatically control sandbox creation, command execution, and metrics streaming across local and cloud backends.

The \sdk/ruby/examples\ directory now includes \lifecycle\_convergence.rb\, a demonstration script that validates the Microsandbox SDK's ability to handle concurrent sandbox creation and connection safely. This example verifies that multiple threads calling \connect\_or\_create\ or \connect\_or\_start\ resolve to a single, consistent sandbox identity without race conditions, and confirms that lifecycle operations like \restart\ and \destroy\ correctly preserve configuration and reject stale handles.

sdk/ruby/examples · high confidence

A new Rust example (\examples/rust/cloud-backend/bin/main.rs\) demonstrates creating, executing commands in, and monitoring logs for a sandbox on the cloud backend, including explicit validation that the cloud backend is selected via environment variables.

examples/rust/cloud-backend · high confidence

A new Rust example named 'bind-root' has been added to the examples directory, demonstrating how to create a sandbox using a local directory as the root filesystem. The example code configures a sandbox with specific CPU and memory limits, executes shell commands within the environment, and then stops the sandbox, providing a concrete usage pattern for the embeddable SDK.

examples/rust/root-bind · high confidence

A new Rust example has been added to the \examples/rust/root-block\ directory that demonstrates how to initialize a sandbox using a qcow2 disk image (specifically Alpine Linux). The example code configures the sandbox with specific CPU and memory limits, mounts the disk image with an ext4 filesystem, and executes shell commands to verify the environment, providing a concrete usage pattern for the block-storage-based sandbox lifecycle.

examples/rust/root-block · high confidence

The SDK now includes a new setup module that provides cross-platform host readiness checks and runtime dependency installation. On Linux, it verifies KVM availability and CPU virtualization flags, offering safe auto-fixes for missing kernel modules. On macOS, it ensures the host is Apple silicon, as Intel Macs are unsupported. On Windows, it checks for the Windows Hypervisor Platform (WHP) and provides instructions to enable it. The module also handles downloading, extracting, and verifying the microsandbox runtime bundle (msb and libkrunfw) to a configurable base directory, with support for CI local bundles and SHA-256 verification.

sdk/rust/lib/setup · high confidence

Added a comprehensive set of Go SDK examples in sdk/go/examples that demonstrate core microsandbox capabilities, including basic sandbox creation and execution, cloud backend integration with live log streaming, detached lifecycle management, disk image mounting, typed error handling, filesystem operations (including streaming), OCI image cache management, network policy configuration, rootfs patches, port publishing, secret injection, snapshot-based forking, and metrics collection.

sdk/go/examples · high confidence

The Go SDK's internal FFI bridge now includes a Windows-compatible dynamic library loader, enabling the SDK to run on Windows platforms. This change adds the necessary C preprocessor logic and platform-specific bindings (using LoadLibrary/GetProcAddress) to load the underlying Rust microsandbox library at runtime on Windows, in addition to the existing Linux and macOS support.

sdk/go/internal/ffi · high confidence

The Go SDK now bundles the \libmicrosandbox\_go\_ffi\ shared library for Windows (amd64 and arm64) alongside existing macOS and Linux targets. This change introduces a new \bundle\ package that embeds platform-specific binaries (\.dll\ for Windows, \.dylib\ for macOS, \.so\ for Linux) directly into the SDK release, allowing the SDK to function on Windows without requiring users to manually install or configure the FFI library. The implementation uses Go build tags to select the correct embedded binary at compile time, with a fallback build tag for developers to use a local library path via the \MICROSANDBOX\_FFI\_PATH\ environment variable.

sdk/go/internal/bundle · high confidence

The Go SDK is now available, providing idiomatic Go bindings to the microsandbox runtime. It enables Go applications to create and manage microVM-backed sandboxes, execute commands (including streaming), interact with the guest filesystem, manage volumes and images, and access network, secrets, and metrics. The SDK includes a cross-SDK raw agent client for low-level protocol access, unified lifecycle APIs for sandbox convergence, and comprehensive error handling aligned with other language bindings.

sdk/go · high confidence

The Go SDK now includes a native Rust-based FFI bridge (microsandbox-go) that exposes core sandbox operations—such as creation, connection, start, stop, kill, drain, and modification—via a C-ABI header. This layer manages opaque sandbox handles and streaming exec sessions, allowing the Go SDK to interact directly with the underlying runtime for full API parity and concurrent safety.

sdk/go/native · high confidence

Adds a new set of Python examples demonstrating the microsandbox SDK capabilities. These include lifecycle management (convergence, cloud backend, init handoff), networking (DNS filtering, policies, port publishing, TLS interception, secret injection), storage (OCI images, bind mounts, block devices, rootfs patches, named/disk volumes), and observability (file streaming, metrics streaming, log reading). The examples also cover interactive shell attachment and snapshot-based sandbox forking, providing reference implementations for common sandbox operations.

examples/python · high confidence

The Python SDK for microsandbox is now available, providing a comprehensive interface for managing secure, fast microVM-based sandboxes. This release includes a full set of lifecycle APIs for creating, connecting to, and removing sandboxes, along with support for executing commands, managing images, and handling volumes. The SDK also exposes low-level agent communication capabilities, detailed error handling, and type-safe configuration options, enabling developers to integrate sandboxing directly into their Python applications.

sdk/python/microsandbox · high confidence

The Python SDK is now available, providing async Python bindings to the microsandbox runtime via PyO3. Users can create and manage microVM-backed sandboxes using a \Sandbox\ class that supports OCI images, bind rootfs, disk images, and snapshots. The SDK exposes comprehensive capabilities including command execution with streaming, guest filesystem operations, named volumes, network policies, secrets, metrics, logs, and SSH/SFTP. It also includes image management (load, save, prune), local and cloud backend routing, and typed Python interfaces with \.pyi\ stubs for type safety.

sdk/python · high confidence

Users can now create and manage isolated microsandboxes using the new Ruby SDK. The library provides a \SandboxBuilder\ for configuring sandbox properties such as CPU, memory, and network settings, and exposes a \Filesystem\ interface to read, write, and manage files within the sandbox environment. It also supports scoped execution via \Sandbox.with\ and allows configuration of outbound proxy credentials.

sdk/ruby/lib · high confidence

The Rust SDK now includes a new \sdk/rust/lib/image\ module that provides a high-level interface for persisting, querying, and removing OCI image metadata in the database. This module exposes static methods on the \Image\ struct for operations such as persisting image metadata, retrieving image details (including config, layers, and labels), and pruning unused images, while leveraging the existing \microsandbox\_image\ global cache for on-disk layer management.

sdk/rust/lib/image · high confidence

The \sdk/rust\ directory now contains the Rust SDK for microsandbox, providing an async API to create and manage microVM-backed sandboxes for isolated execution of AI agents, tools, and untrusted code. Users can install the \microsandbox\ crate via Cargo and leverage features such as OCI image-based sandboxes, guest filesystem operations, named volumes, network policies, and detached sandbox lifecycles. The SDK includes a \connect\_or\_create\ mechanism for convergent sandbox lifecycle management, allowing stable IDs and persistent state across process restarts. Additionally, the SDK bundles a self-healing runtime installer (\bin/main.rs\ and \build.rs\) that automatically downloads and installs the \msb\ binary and \libkrunfw\ library on first run, ensuring the runtime is available without manual setup on supported platforms (Linux, macOS, and preview Windows).

sdk/rust · high confidence

The \sdk/node-ts\ directory now contains the initial implementation of the microsandbox TypeScript SDK, providing an ESM-first API with CommonJS support for Node.js 22+. This release introduces a builder-based API for creating and managing microVM sandboxes, supporting features such as command execution, guest filesystem operations, named volumes, network policies, and detached lifecycle management. The SDK is implemented as a native addon using \napi-rs\ (evidenced by \build.rs\ and \.gitignore\ patterns like \\*.node\), with configuration files (\tsconfig.json\, \vitest.config.ts\) establishing the build and test environment.

sdk/node-ts · high confidence

A new \microsandbox\ executable script has been added to the SDK's bin directory. This Node.js shim acts as a wrapper that automatically detects the user's platform (macOS, Linux, or Windows) and architecture, then locates and executes the corresponding native \msb\ binary from the bundled platform-specific packages. It supports overriding the binary location via the \MSB\_PATH\ environment variable and ensures that command-line arguments are passed through correctly to the underlying tool.

sdk/node-ts/bin · high confidence

Users can now generate shell completion scripts for Bash, Zsh, Fish, Elvish, and PowerShell using the new \msb completion\ command. This allows the CLI to provide tab-completion for commands and flags in supported shells, improving interactive usability.

crates/cli/lib/commands · high confidence

The SDK now includes a new \CloudBackend\ implementation located in \sdk/rust/lib/backend/cloud\, enabling users to manage sandboxes, volumes, and logs via the msb-cloud control plane. This change adds HTTP and WebSocket plumbing for sandbox lifecycle operations (create, start, list, get, remove), paginated sandbox listings, volume management (including file system read/write streams), and log streaming over Server-Sent Events (SSE). It also provides a byte-stream adapter (\WsByteStream\) to bridge WebSocket connections for agent communication, allowing the SDK to interact with cloud-hosted sandboxes using the same high-level APIs as local backends.

sdk/rust/lib/backend/cloud · high confidence

The configuration schema for the microsandbox library now supports setting a global deployment profile (single-tenant or multi-tenant) via \config.json\, allowing operators to enforce a specific isolation policy that overrides per-sandbox defaults. Additionally, SSH session behavior is now configurable, with a new \SshConfig\ section allowing users to define an inactivity timeout to automatically disconnect idle sessions. These changes are implemented in the \GlobalConfig\ structure and its associated serialization logic within the Rust SDK's config module.

sdk/rust/lib/config · high confidence

The \crates/metrics-collector/lib/core\ module now provides the foundational machinery for the metrics collector, including a builder, run-loop driver, and per-exporter workers. This change introduces a default 30-second staleness filter that stops emitting metrics for sandboxes whose shared-memory samples have not updated, preventing frozen metrics from stale or unreleased slots. It also adds per-sandbox label enrichment, resolving labels from the SQLite catalog and attaching them to emitted metrics, with support for excluding specific label keys to control cardinality.

crates/metrics-collector/lib/core · high confidence

The image library now includes a new global on-disk cache system that stores OCI layers, EROFS images, VMDK descriptors, and manifest metadata in a structured directory layout under the user's cache directory. This change introduces cross-process file locking mechanisms to coordinate concurrent access to shared cache artifacts during download and materialization pipelines, ensuring data integrity when multiple processes interact with the cache simultaneously.

crates/image/lib/cache · high confidence

The \crates/metrics\ library now provides a POSIX shared-memory based metrics registry that replaces the previous continuous SQLite catalog inserts. This change enables low-latency, live metric collection for running sandboxes by allowing the runtime to write samples directly into a shared-memory slot, which readers can scan to produce typed metric responses without per-sample RPC or database writes. The implementation includes a defined binary layout for the shared region, error handling for registry operations, and snapshot types for reading live sandbox metrics such as CPU, memory, disk, and network usage.

crates/metrics · high confidence

The \metrics-collector\ library now provides a structured way to collect and export per-sandbox metrics. It includes an OTLP exporter (\OtelExporter\) that ships metrics like CPU utilization, memory usage, disk I/O, and network traffic to any OpenTelemetry-compatible backend, and a human-readable \StdoutExporter\ for local debugging. The library also defines a dedicated error type (\MetricsCollectorError\) to decouple collector errors from the main microsandbox error space and exposes the core collector orchestrator for integration.

crates/metrics-collector/lib/exporters · high confidence

The \crates/agentd\ crate is added, providing the \microsandbox-agentd\ binary that runs as PID 1 inside the microVM guest. It handles synchronous initialization (mounting filesystems, applying network and security configurations) and then transitions into an asynchronous agent loop that manages process execution, file I/O, and TCP sessions via a virtio serial port. A key capability is the optional PID 1 handoff, which allows the agent to fork and exec a guest init binary (like systemd) while the agent continues running as a child process to serve host requests. The agent also includes a dedicated OS thread for heartbeat liveness pulses to prevent starvation by the async runtime.

crates/agentd · high confidence

A new \msb-metrics\ binary has been added to collect metrics from the microsandbox shared-memory registry and ship them to OpenTelemetry-compatible backends or stdout. It supports configurable collection and flush intervals, buffer limits, and export timeouts. Users can configure OTLP endpoints with gRPC or HTTP protocols, TLS via CA certificates, custom headers, and resource attributes. The tool allows controlling metric cardinality by optionally emitting sandbox run IDs or PIDs, disabling per-sandbox labels entirely, or excluding specific high-cardinality label keys. It also includes a safeguard to stop emitting metrics for sandboxes that have stopped updating their shared-memory slots.

crates/metrics-collector/bin · high confidence

The \microsandbox-types\ package now includes a Rust derive macro (\ConfigPatch\) and supporting infrastructure that generates sparse, presence-aware modification patches for sandbox configuration structs. This allows the SDK and CLI to send only the fields that have changed (preserving presence semantics) when modifying running sandboxes, rather than requiring full object replacement. The macro supports nested struct patching, collection merging (via \Extend\ or custom functions), and explicit field clearing, ensuring that partial updates do not inadvertently overwrite unchanged values. This change underpins the \sandbox.modify()\ API by providing a backend-neutral, serializable contract for incremental configuration changes.

packages/microsandbox-types · high confidence

This change adds the \packages/agent-client\ package, providing low-level clients for the microsandbox agent protocol in both Rust (\microsandbox-agent-client\) and TypeScript (\@microsandbox/agent-client\). These libraries handle transport-agnostic connection handshakes, correlation ID allocation, request/stream routing, and message encoding (CBOR), sitting between the protocol definitions and high-level SDKs. The Rust implementation supports Unix domain sockets (via the \uds\ feature), Windows named pipes (via the \named-pipe\ feature), and generic byte streams (via the \stream\ feature). The TypeScript package exposes browser-safe WebSocket support by default, with Node-specific Unix domain socket access available via a separate entry point. Both implementations enforce protocol version gating and provide typed and raw APIs for interacting with the agent relay.

packages/agent-client · high confidence

The \crates/filesystem/lib/backends\ directory now includes a new \dualfs\ backend that merges two child filesystems (backend\_a and backend\_b) into a single unified view for the guest. This component introduces a builder API for configuring the merged filesystem, a lifecycle hook system for intercepting and influencing operations, and a set of built-in dispatch policies (such as \BackendAOnly\, \BackendAFallbackToBackendBRead\, and \MergeReads\) that determine how reads, writes, and lookups are routed between the backends. It also implements the core FUSE operations (lookup, create, open, read, write, readdir, getattr, setattr) and materialization logic to handle copy-up and state transitions between the two backends.

crates/filesystem/lib/backends · high confidence

Added a Rust example demonstrating how to configure network policies to block specific domains and domain suffixes within a sandboxed environment.

examples/rust/net-dns · high confidence

The Rust SDK now includes an FFI-friendly \AgentBridge\ in \sdk/rust/lib/agent/bridge.rs\ that exposes sandbox agent communication via opaque \u64\ stream handles and raw CBOR frames, enabling Node/Python/Go bindings to interact with the agent without owning Rust async types. Additionally, the SDK introduces a comprehensive log streaming system (\sdk/rust/lib/logs/\) that reads \exec.log\, \runtime.log\, and \kernel.log\ with rotation-aware parsing, per-source \LogCursor\ resume handles, and a \LogRegistry\ that shares a single filesystem watcher across multiple followed streams to prevent inotify exhaustion on hosts with many sandboxes.

sdk/rust/lib/sandbox · high confidence

Added Rust examples demonstrating the new embeddable SDK's capabilities: basic networking (DNS, HTTP, interface status), port publishing, secret injection with TLS interception, TLS interception with per-domain certificate generation, OCI root sandboxing, and named volumes for persistent storage.

(repo-wide) · high confidence

A new Rust example (\examples/rust/net-secrets-body\) has been added to demonstrate injecting secrets into HTTP request bodies via the TLS proxy. The example sets up a mock HTTPS server and a sandboxed guest that POSTs a secret key; the \microsandbox\ SDK is configured with \inject\_body(true)\ to ensure the secret is substituted in the HTTP payload, while \upstream\_ca\_cert\ is used to trust the server's self-signed certificate during TLS interception.

examples/rust/net-secrets-body · high confidence

Added a new Rust example (\examples/rust/lifecycle-convergence/bin/main.rs\) that validates the sandbox SDK's ability to handle concurrent lifecycle operations safely. The example verifies that multiple simultaneous calls to \connect\_or\_create\ and \connect\_or\_start\ resolve to a single sandbox identity, ensuring that lifecycle ownership and environment markers are preserved correctly during concurrent access, restarts, and destruction.

examples/rust/lifecycle-convergence · high confidence

The volume-disk example now demonstrates how to attach raw and qcow2 disk images to a sandbox. It shows mounting a read-only ext4 image at /seed and a read-write ext4 image at /data, verifying access by reading a file from the seed and writing a new file to the data volume.

examples/rust/volume-disk · high confidence

Added a Rust example in \examples/rust/snapshot-fork\ that demonstrates creating a file-based disk snapshot of a stopped sandbox and booting a new sandbox instance from that snapshot. The example shows how to prepare a baseline sandbox, stop it, create a snapshot, and then fork a new sandbox from the snapshot state, verifying data persistence across the fork.

examples/rust/snapshot-fork · high confidence

Added a Rust example in examples/rust/shell-attach that demonstrates how to connect to or create a sandbox and attach an interactive shell session. The example uses the Sandbox builder to configure an Alpine image with 1 CPU and 512MB memory, then calls attach\_shell to bridge the terminal to the sandbox, allowing users to detach with Ctrl+\] or exit the session.

examples/rust/shell-attach · high confidence

The \examples/rust/logs-read\ directory now includes a Rust binary that demonstrates how to read captured execution logs from a stopped sandbox. The example shows how to retrieve default user-program output (stdout, stderr, and output), how to include system-level diagnostics and lifecycle markers by adding the \System\ source, and how to limit results using the \tail\ option.

examples/rust/logs-read · high confidence

Added a Rust example in examples/rust/metrics-stream that demonstrates how to subscribe to a sandbox's resource usage metrics. The example creates an Alpine sandbox, generates background load, and then streams CPU, memory, and disk I/O metrics at one-second intervals for five iterations.

examples/rust/metrics-stream · high confidence

Added two Rust example programs demonstrating new SDK capabilities: \fs-read-stream\ shows how to create a sandbox, generate a file, and stream its contents back in chunks using the new \read\_stream\ API, while \init-handoff\ demonstrates handing PID 1 over to a guest init binary (like systemd) by configuring the sandbox with \.init("auto")\.

examples/rust/fs-read-stream · high confidence

The SDK now includes a new Rust runtime library (\sdk/rust/lib/runtime\) that provides the core primitives for managing sandbox processes. This module introduces \ProcessHandle\ for controlling running sandboxes (including sending signals like SIGKILL and SIGUSR1 for graceful drains, waiting for exit, and handling detached modes) and \NetworkSlot\ for atomically leasing and recycling network address-pool slots from the local database. It also adds \reap.rs\ for identity-checked termination of leaked sandbox processes on Windows to prevent accidental killing of recycled PIDs, and \spawn.rs\ for assembling CLI arguments and launching the sandbox process. This library serves as the foundational runtime layer for the Rust SDK.

sdk/rust/lib/runtime · high confidence

Added a comprehensive set of TypeScript examples in the \examples/typescript\ directory that demonstrate the redesigned microsandbox SDK. These examples cover core sandbox lifecycle operations (including \connectOrCreate\, \connectOrStart\, and concurrency safety checks), cloud backend integration, and interactive shell attachment. They also showcase advanced capabilities such as streaming file reads (\fs-read-stream\), real-time resource metrics (\metrics-stream\), and log retrieval (\logs-read\). Networking examples illustrate basic connectivity, DNS filtering, network policies, port publishing, secret injection, and TLS interception. Storage and initialization examples demonstrate OCI image roots, bind-mounted directories, qcow2 disk images, pre-boot filesystem patches, init handoff to systemd, named volumes, disk volumes, and disk-snapshot forking.

examples/typescript · high confidence

The SDK now exposes a new policy API in the \sdk/node-ts/src/policy\ module, allowing users to define network access rules programmatically. This includes factory functions for creating ingress/egress allow/deny rules, specific helpers for DNS traffic, and a \NetworkPolicy.fromProfiles\ method that builds a deny-by-default policy based on composable profiles (public, private, host). Users can now configure granular network policies using the new \Rule\, \Destination\, and \PortRange\ builders.

sdk/node-ts/src/policy · high confidence

This change introduces several new scripts to the repository. The \bump-version.sh\ script automates the process of updating the microsandbox version across all Rust, Node.js, and Go manifests and lockfiles in a single operation. Windows support is enabled through \install.ps1\ and \dev-windows.ps1\, which handle downloading, verifying, and installing the release bundle, as well as managing local development builds and environment paths. Additionally, \install.sh\ is updated to link commands to the local bin directory and enforce a minimum glibc version for Linux, while \check-docs-language-order.py\ and \sync-docs-openapi.py\ enforce documentation consistency and generate the public Cloud API reference from the live OpenAPI spec.

scripts · high confidence

The database layer now includes SeaORM entity definitions for tracking sandbox runs and their termination reasons, managing OCI image manifests and layers, and handling CPU, memory, and writeback resource allocations. New tables support sandbox labels, rootfs modes (EROFS, bind, disk-image), and snapshot indexing, enabling the runtime to persist sandbox state, coordinate host resources, and manage image artifacts.

crates/db/lib/entity · high confidence

The \crates/image/lib\ crate introduces a complete OCI image handling pipeline. It adds registry authentication (basic auth and anonymous access) and platform-aware manifest resolution. The library implements content-addressable caching for layer downloads with resume support and progress reporting. It provides EROFS filesystem support, including a writer for generating metadata-only images for fsmerge and a reader for extracting file contents. Additionally, it supports materializing flat ext4 root filesystems from cached EROFS layers, handling the full lifecycle from pull to materialization.

crates/image/lib · high confidence

The \crates/protocol/lib\ crate now defines the complete host-to-guest agent protocol, introducing a new wire format using length-prefixed frames with a binary header (correlation ID and flags) followed by a CBOR payload. This change adds typed message structures for core lifecycle events (ready, ping/pong, clock sync, shutdown), command execution (including PTY support, resource limits, and detailed failure classification), filesystem operations (streaming read/write, directory listing, metadata updates), and TCP stream management. It also introduces a \GuestBootstrap\ configuration type for delivering one-time initialization data (mounts, network, security profiles, environment) to the guest agent at boot, alongside a \RawFrame\ codec that allows relay intermediaries to route messages without parsing the CBOR body.

crates/protocol/lib · high confidence

The \crates/filesystem\ location introduces the \microsandbox-filesystem\ crate, providing three composable filesystem backends for virtual machines: \PassthroughFs\ (exposing a host directory with virtualized permissions), \MemFs\ (in-memory storage), and \DualFs\ (combining backends with configurable read/write policies). The build system now supports offline builds by allowing the \agentd\ binary to be staged via the \MSB\_AGENTD\_PATH\ environment variable or downloaded as a prebuilt artifact, ensuring the guest agent is correctly embedded without requiring network access during compilation.

crates/filesystem · high confidence

A new \microsandbox-filesystem\ crate has been introduced, providing the foundational filesystem utilities for the microsandbox architecture. This includes an embedded \agentd\ binary (accessible via \AGENTD\_BYTES\) for inclusion in guest images, and platform-specific backend modules: on Unix, it exposes \DualFs\, \MemFs\, \PassthroughFs\, and \SingleFileFs\ with associated configuration and caching policies; on Windows, it exposes \PassthroughFs\ (with host permissions and stat-virtualization) and \SingleFileFs\. The crate also re-exports core FUSE-related types from \msb\_krun\ and size utilities from \microsandbox\_utils\.

crates/filesystem/lib · high confidence

The Node.js SDK now uses a native Rust implementation (via NAPI-RS) instead of the previous JavaScript-only approach. This introduces a comprehensive set of new classes and builders for sandbox configuration and interaction, including \AgentClient\ for raw protocol communication, \SandboxFsOps\ for file system operations, \ExecHandle\ for command execution, and fluent builders for DNS, image, and execution options. The change also includes a new error handling system that maps Rust error variants to typed JavaScript error codes, and adds support for loading platform-specific native binaries (Windows, macOS, Linux, Android).

sdk/node-ts/native · high confidence

Added a Rust example demonstrating how to configure network policies within a sandbox, including default, allow-all, and custom rules.

examples/rust/net-policy · high confidence

The Node SDK now includes build and release scripts to streamline publishing and validation. The \prepare-platform-package\ script bundles the native N-API binding, the \msb\ CLI, and the \libkrunfw\ shared library into platform-specific npm packages, handling OS-specific requirements like macOS codesigning and canonical library naming. A new \prune-platform-optional-deps\ script cleans up legacy optional dependencies from the package manifest. Additionally, a \cloud-release-smoke\ script and its tests exercise candidate packages against the production cloud environment to verify sandbox creation and cleanup before release.

sdk/node-ts/scripts · high confidence

An example Rust application has been added to demonstrate how to apply filesystem patches to a sandbox's rootfs before it starts. The code shows how to use the microsandbox SDK to write text files, create directories with specific permissions, and append content to existing files, allowing users to customize the guest environment at boot time.

examples/rust/rootfs-patch · high confidence

The \crates/utils\ library introduces a suite of shared primitives for the microsandbox platform. It adds sparse-aware file copying that preserves holes via reflinks or extent-based copying, and filesystem allocation scanning to identify data extents. Process helpers now distinguish live processes from zombies to prevent SDKs from waiting on exited sandboxes. State management is isolated via the \MSB\_HOME\ environment variable, which allows CI and tests to use custom directories without affecting the default \\~/.microsandbox\ location. Additional utilities include cross-platform process file locking, ANSI log stripping, type-safe byte-size conversions, and a TTL-indexed reverse map for managing expiring key-member associations.

crates/utils · high confidence

The Node.js SDK has been completely redesigned to use native NAPI classes for fluent builders (SandboxBuilder, VolumeBuilder, SnapshotBuilder, etc.) and bundled binaries, replacing the previous implementation. This change introduces a new low-level AgentClient for raw protocol communication, adds comprehensive filesystem operations (FsReadStream, FsWriteSink, SandboxFsOps), and provides new capabilities for live sandbox modification (modify, resize), SSH client/server support, and detailed metrics streaming. Error handling is now unified through a typed MicrosandboxError hierarchy, and the SDK exports new types for deployment profiles, network configuration, and image management.

sdk/node-ts/src · high confidence

The network subsystem has been restructured to support a new smoltcp-based in-process networking engine. This change introduces a fluent builder API for network configuration, allowing users to define port mappings, DNS settings, TLS interception, and rate limits programmatically. It also implements a new DNS forwarder that intercepts queries on ports 53 and 853, applying egress policies, block lists, and DNS rebinding protection before forwarding to upstream resolvers. Additionally, the module includes helpers for normalizing IP addresses (including IPv4-mapped IPv6) and classifying DNS transport types.

crates/network · high confidence

The repository has been initialized with the foundational structure for the Microsandbox project. This includes standard configuration files such as \.gitignore\, \.dockerignore\, and \.gitattributes\ to manage build artifacts and line endings, as well as development tooling like \pre-commit\ hooks for Rust formatting and linting. The project layout is defined with a Cargo workspace containing core crates (CLI, runtime, filesystem, network, etc.) and language-specific SDKs (Rust, Python, Node.js, Go). Documentation files including \AGENTS.md\, \DEVELOPMENT.md\, and \COMPATIBILITY.md\ provide guidelines for contributors, setup instructions, and backward-compatibility boundaries. Submodules are configured for external dependencies like \libkrunfw\, example root filesystems, and MCP integration.

(repo-wide) · high confidence

The Ruby SDK now ships with a native C/Rust extension (microsandbox) that provides production-ready bindings to the core sandboxing engine. This addition introduces a new \extconf.rb\ build script and a substantial Rust source file (\lib.rs\) that exposes core sandbox lifecycle, execution, and backend selection APIs directly to Ruby, enabling Ruby applications to manage sandboxes with lower overhead than pure-Ruby implementations.

sdk/ruby/ext/microsandbox · high confidence

The runtime now persists structured startup failure details to a \boot-error.json\ file, allowing the CLI to surface actionable causes (such as mount, VM build, or network errors) instead of generic process exit codes. Additionally, the runtime introduces NUMA-aware CPU placement profiles that discover host topology and coordinate vCPU and memory allocation across NUMA nodes to optimize performance.

crates/runtime · high confidence

The image library now supports importing and exporting container images as archives. Users can load images from Docker-compatible or OCI layout archives and save local images into these formats. The implementation includes support for nested OCI image indexes and preserves long symbolic link targets in saved archives, ensuring compatibility with standard container tooling.

crates/image/lib/archive · high confidence

The SDK now routes all sandbox and volume operations through a unified \Backend\ trait that supports both local (libkrun) and cloud (msb-cloud) implementations. This introduces a new configuration system where users can select a backend via environment variables (\MSB\_BACKEND\, \MSB\_API\_KEY\) or named profiles defined in \\~/.microsandbox/config.json\. The system enforces a strict precedence ladder, ensuring that explicit programmatic or environment selections override profile settings, and provides a fail-closed \ConfigurationErrorBackend\ to prevent silent failures when cloud credentials are missing or invalid.

sdk/rust/lib/backend · high confidence

The volume module now exposes a single, backend-agnostic \VolumeFs\ API for reading, writing, and listing files within named volumes. This implementation unifies local disk access (via \tokio::fs\) and cloud storage (via HTTP streaming) under one interface, allowing users to perform filesystem operations on volumes regardless of whether they are stored locally or in the cloud. The change introduces streaming read and write capabilities (\VolumeFsReadStream\ and \VolumeFsWriteSink\) to handle large files efficiently across both backends, while maintaining a consistent public surface for volume management.

sdk/rust/lib/volume · high confidence

The core Rust SDK library has been moved to the sdk/rust/lib directory, introducing a new error.rs module that defines the MicrosandboxError enum with variants for cloud HTTP failures, sandbox lifecycle states (not found, already exists, replaced, still running), boot/startup failures, execution timeouts, and snapshot integrity checks. The lib.rs module now explicitly re-exports public API surfaces including backend selection (cloud/local), image/volume/snapshot management, sandbox configuration patches, network policy builders, and SSH operations, while test\_support.rs provides environment locking for unit tests. This structural change consolidates the SDK's public interface and error handling in a single, well-organized crate location.

sdk/rust/lib · high confidence

The \crates/migration\ crate now provides the complete database migration path for the microsandbox catalog, ensuring the schema aligns with the v0.6.16 release. This includes the foundational image, sandbox, and storage tables, alongside critical structural updates such as the EROFS-backed OCI rootfs schema, the replacement of the legacy snapshot table with a digest-keyed index, and the removal of the deprecated \sandbox\_metric\ table. The migration also introduces support for sandbox labels, named volume kinds, ephemeral sandbox lifecycle tracking, and active configuration management.

crates/migration · high confidence

The database layer now distinguishes between read and write operations using typed connection wrappers (\DbReadConnection\ and \DbWriteConnection\). This ensures that writes are serialized through a single-connection pool to prevent SQLite contention, while reads can scale across multiple connections. Additionally, the write path now automatically retries transient \SQLITE\_BUSY\ errors with exponential backoff, improving reliability when multiple processes access the database simultaneously.

crates/db/lib · high confidence

The local backend implementation has been refactored to use a \LocalBackend\ struct that encapsulates configuration and database state, replacing the previous per-process global config and SQLite pool statics. This change allows for multiple backend instances with distinct configurations, supporting better test isolation and migration handling. The backend can be constructed lazily for ambient default access or eagerly via a builder for programmatic configuration, with database connections and migrations initialized on first use.

sdk/rust/lib/backend/local · high confidence

The local sandbox backend now supports a new create flow that allows users to provision sandboxes using flat OCI root disks instead of the traditional layered approach, which skips VMDK materialization for faster boot times. This change introduces a unified lifecycle API where the \LocalBackend\ manages the entire sandbox state machine—including image pulling, rootfs preparation, and process spawning—through a single entry point. The implementation adds strict state transitions and transition guards to ensure database and host resource consistency during creation and startup, preventing race conditions when starting or recreating sandboxes.

sdk/rust/lib/backend/local/sandbox · high confidence

The snapshot library now uses a new schema-1 descriptor (\snapshot.json\) as the source of truth for snapshot artifacts, replacing the legacy \manifest.json\ format. This new descriptor defines a strict content-addressed identity using SHA-256 over canonical JSON and supports both file-backed disk snapshots and checkpoint-based resumable states. To ensure compatibility with existing artifacts, the library includes a bidirectional migration module that can translate legacy v0.6.6 descriptors into the new schema-1 format and vice versa, allowing for safe upgrades and downgrades of snapshot metadata.

crates/image/lib/snapshot · high confidence

The \msb\ CLI now organizes its top-level commands into logical groups (Sandboxes, Images, Storage, Installation) for improved help readability. This change introduces new self-management capabilities, including \install\, \uninstall\, \update\, \downgrade\, and \doctor\ commands, alongside a new \completion\ command for shell integration. Existing sandbox operations like \run\, \create\, \modify\, \start\, \stop\, \restart\, \ping\, \touch\, \list\, \status\, \metrics\, \remove\, \exec\, \copy\, \logs\, \ssh\, and \inspect\ are retained, while image management is expanded with \pull\, \load\, \save\, and \registry\ commands. Internal commands such as \Sandbox\, \\_\schema-baseline\, and \\\_windows-self-swap\ are hidden from standard help output.

crates/cli/bin · high confidence

The CI pipeline now includes a suite of new operational scripts to improve reliability and correctness of builds and releases. Runner disk cleanup is handled by a hardened script that safely prunes stale temporary directories without deleting the active checkout, while a new runner provisioning script manages self-hosted GitHub Actions runners with distinct users and work trees to prevent collisions. Release integrity is enforced by validators that check for the presence of all expected cross-platform artifacts, verify that bundled executables retain their executable permissions, and ensure Linux binaries do not exceed the supported glibc baseline (2.28). Additionally, new helpers manage Rust crate publication in dependency order, wait for npm package propagation, and optimize Ruby SDK builds by reusing native build inputs.

scripts/ci · high confidence

The registry module has been restructured to introduce a \RegistryBuilder\ for configuring authentication, TLS settings (including custom CA certificates and insecure registries), and platform-specific image resolution. The new \Registry\ client wraps the underlying OCI client to provide platform-aware manifest resolution, caching support (including lookup by immutable manifest digest for snapshot restores), and concurrent layer download with progress reporting during EROFS materialization.

crates/image/lib/registry · high confidence

The Node.js TypeScript SDK has been rebuilt to use native NAPI classes instead of the previous JavaScript wrapper layer, introducing a fluent builder API for configuring sandboxes, volumes, and snapshots. This change bundles platform-specific binaries (including Windows support) directly with the SDK, handling binary resolution and runtime path configuration internally. It also introduces structured error mapping that converts native error strings into specific TypeScript error classes, adds metrics collection for sandbox resource usage, and provides an internal async iterator for streaming data from the native layer.

sdk/node-ts/src/internal · high confidence

The image library has been reorganized into dedicated submodules for specific image formats. The \stitch\ module now encapsulates VMDK descriptor generation logic, including extent handling and validation, while the \tar\ module centralizes OCI layer ingestion, supporting gzip and zstd compression with comprehensive error handling for path traversal, size limits, and whiteout semantics.

crates/image/lib/stitch, crates/image/lib/tar · high confidence

The snapshot system in \sdk/rust/lib/snapshot\ now requires an explicit \record\_integrity\ flag to compute and store persistent payload integrity (Merkle digests) for the upper layer. By default, snapshots are created without this overhead, which reduces creation time and storage size for large allocated uppers. Users who need content verification must explicitly enable the feature when creating a snapshot.

sdk/rust/lib/snapshot · high confidence

The CLI now renders detailed, styled error blocks for sandbox boot failures and command execution errors. When a sandbox fails to start, users see a clear cause line indicating the failure stage (mount, build\_vm, config, network, image, or other) along with specific, actionable hints—for example, suggesting to check host path permissions on mount errors or to pull an image on rootfs-not-found errors. Similarly, when a command fails to execute inside a sandbox, the CLI displays the failure reason (such as command not found, permission denied, or bad working directory) and provides targeted troubleshooting advice, such as checking PATH or binary permissions. These improvements replace generic error messages with structured, user-friendly diagnostics that guide users toward resolution.

crates/cli/lib · high confidence

The ext4 image library now supports growing upper disk images that were created by the pre-0.6.9 formatter. The new offline resizer in \crates/image/lib/ext4/resizer.rs\ detects these legacy images by their specific feature flags and structural invariants (notably the absence of a resize inode) and applies the correct layout offsets. This allows existing legacy upper disks to be expanded in place without requiring recreation.

crates/image/lib/ext4 · high confidence

Added Node.js SDK smoke tests; Added fuzzing target for snapshot archive unpacking; Added integration and unit tests for the Ruby Microsandbox SDK; Added integration tests for CLI exec, streaming, live resize, and SSH features; Added integration tests for the msb-metrics CLI and OTLP exporter; Added protocol schema snapshot tests; Added unit tests for the redesigned TypeScript SDK; Expanded integration test coverage for the Rust SDK; Expanded test coverage for Python SDK configuration and serialization; Go SDK integration test suite; New smoke tests for image archives, legacy sandbox compatibility, and upgrade paths; New test infrastructure for isolated microsandbox integration tests; Python SDK integration test suite added.

This release updates the microsandbox workspace to version 0.6.18, including the Rust SDK, CLI, and internal crates. The dependency manifest refreshes several Rust libraries, notably bumping \tokio\ to 1.52, \reqwest\ to 0.13, and \sea-orm\ to 2.0, while also updating \msb\_krun\ to 0.1.32. These changes ensure compatibility with the latest runtime features and security patches across the microsandbox platform.

(dependencies) · high confidence

The Microsandbox Ruby SDK version constant has been updated to 0.6.18, reflecting the latest release in the SDK series.

sdk/ruby/lib/microsandbox · high confidence

The libkrunfw vendor submodule has been updated to commit 21cb6dc. This change reflects an upstream update to the underlying virtualization library used by the platform.

vendor · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 74.

• Code Health 86
• Architecture 85
• Maturity 71
• Readiness 78
• Security 70
• Domain Modelling 100
• Event Sourcing 100

• 300 commits — 239 feature/other, 61 fixes

• (repo) — 75 commits
• docs/sdk — 52 commits
• sdk/node-ts — 19 commits
• sdk/rust — 17 commits
• .github/workflows — 16 commits
• docs/changelog — 15 commits
• (root) — 13 commits
• crates/network — 11 commits
• docs/sandboxes — 10 commits
• examples/typescript — 10 commits
• crates/runtime — 7 commits
• crates/cli — 6 commits
• docs/cli — 6 commits
• docs/examples — 6 commits
• crates/filesystem — 4 commits
• docs/networking — 4 commits
• crates/agentd — 3 commits
• crates/image — 3 commits
• crates/migration — 3 commits
• crates/utils — 2 commits

• fix: Merge pull request #1275 from superradcompany/agent/fix-mintlify-reference-overviews
• fix: Merge pull request #1319 from superradcompany/toks/fix-typescript-doc-drift
• fix: Merge pull request #1325 from lyb2320/fix/mount-permission-diagnostic
• fix: Merge pull request #1405 from superradcompany/appcypher/fix-live-modify-animation
• fix: Merge pull request #1427 from superradcompany/appcypher/fix-docs-sdk-cli-config
• fix: chore(docs): merge mintlify into link fixes
• fix: chore: merge mintlify spelling fixes, keeping corrected rust anchors
• fix: chore: merge mintlify typo fixes, keeping corrected rust anchors
• fix: fix name
• fix: fix(agentd): centralize child process reaping (#1212)
• fix: fix(agentd): create standard stream symlinks during initialization (#1560)
• fix: fix(ci): harden pull request runners and caches (#1347)
• fix: fix(cli): parse dns network rules in release builds (#1302)
• fix: fix(cli): remove backend notices and add mod alias (#1423)
• fix: fix(cli): stop temporary exec sandboxes on errors (#1424)
• fix: fix(docs): make live modify animation production-safe
• fix: fix(filesystem): avoid write probes on readonly mounts (#1446)
• fix: fix(filesystem): isolate single-file mounts (#1464)
• fix: fix(go): use alternate signal stack on macOS (#1310)
• fix: fix(image): load nested OCI image indexes (#1308)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

superradcompany/microsandbox was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.