superradcompany/microsandbox
68.2
Adequate · 14 November 2026
471.6k
lines of production code
Rust
primary language
4
measurements over time
What this system is
Features
Add EROFS image support for block-backed root filesystems
The image library now includes a complete EROFS writer and reader, enabling the creation of block-backed OCI root filesystems. This change introduces the \fsmeta\ module to generate metadata-only EROFS images that reference data in external layer blobs via a device table, supporting chunk-based inode layouts for regular files. The new \writer\ module handles the serialization of inodes, directory entries, and superblocks, while the \reader\ module provides functionality to extract file contents and walk the filesystem tree. This capability allows the system to package and serve root filesystems using the EROFS format, which is optimized for read-only, block-backed storage scenarios.
crates/image/lib/erofs · high confidence
Add Ruby example for sandbox lifecycle convergence and identity safety
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
Add Rust cloud backend lifecycle example
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
Add bind-root example for sandboxing a local directory
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
Add block-root example demonstrating sandbox creation from a qcow2 disk image
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
Add opt-in helper to trust the sandbox CA in Chrome and Java
Users can now explicitly import the sandbox's TLS interception CA into the trust stores of Chrome/Chromium and Java applications using the new \scripts/msb-trust\ helper. This tool detects installed applications, reports missing dependencies (such as \certutil\ or \keytool\), and safely updates the respective trust stores (NSS for Chrome, JDK cacerts for Java) while preserving existing certificates. It is an opt-in step required for these applications to trust the sandbox's intercepted traffic.
scripts/msb-trust · high confidence
Add scoped VSOCK routes with host Unix socket and named pipe backends
The vsock crate now supports scoped VSOCK routes that connect guest sockets to existing local host endpoints. On Unix systems, this is implemented via Unix datagram and Unix stream backends, which route traffic to host-side Unix sockets while enforcing a configurable limit on active peers to prevent resource exhaustion. On Windows, a named pipe backend provides equivalent stream connectivity to local named pipes. These changes enable the runtime to expose VSOCK services through local IPC mechanisms with proper connection lifecycle and peer management.
crates/vsock · high confidence
Automated Rust release publishing with dependency ordering
Added a Python script to the CI pipeline that manages the publication of Rust crates by calculating dependency order waves, ensuring that crates are published in the correct sequence to avoid registry conflicts. The tool validates package manifests, computes a publication closure based on workspace dependencies, and handles registry visibility checks with timeouts.
python · high confidence
Checkpoint and snapshot subsystem rewritten with explicit flush policies and cache management
The runtime's checkpoint and snapshot capabilities have been significantly restructured to support explicit guest filesystem flush policies, configurable filesystem state limits, and memory cache cleanup. This change introduces a new checkpoint coordinator that manages same-epoch captures of owned disk chains and independent named block volumes, ensuring data integrity through explicit rollover and compaction logic. It also adds a memory cache system that allows for observed usage reporting and cooperative reclamation of published RAM files, improving resource management during snapshot operations.
crates/runtime · high confidence
DNS interception and forwarding engine added
The network engine now includes a complete DNS interception and forwarding system. This adds a UDP interceptor and TCP/DoT proxies that capture guest DNS queries, routing them through a central forwarder. The forwarder applies operator-configured block lists and rebind protection (filtering private/reserved IP ranges in responses), enforces network egress policies for direct upstream resolution, and supports upstream selection via configured nameservers or guest-specified targets. It handles plain DNS (UDP/TCP port 53), DNS over TLS (DoT port 853), and classifies alternative DNS protocols (DoQ, mDNS, LLMNR) for refusal or fallback. The system also includes host-specific nameserver discovery (e.g., macOS SCDynamicStore, Linux resolv.conf) and builds upstream clients using the Hickory DNS library with configurable timeouts and TLS verification.
crates/network/lib/engine/dns · high confidence
Go SDK example suite for sandbox lifecycle and operations
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
Go SDK now supports Windows via FFI loader
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
Go SDK now supports Windows via embedded FFI libraries
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
Introduce Go SDK for microsandbox
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
Introduce Go SDK native FFI layer for sandbox lifecycle management
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
Introduce IP destination classification and NAT64 policy support
Added a new network policy engine that classifies IP addresses into specific destination groups (Host, Metadata, Loopback, Private, LinkLocal, Multicast, Public) to enforce granular access rules. The implementation includes logic to handle NAT64 prefixes by projecting IPv6 addresses to embedded IPv4 for policy matching, ensuring that traffic destined for NAT64 addresses is correctly evaluated against the defined policy groups.
crates/network/lib/engine/policy · high confidence
Introduce Python SDK examples for sandbox lifecycle, networking, and storage
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
Introduce Python SDK for microsandbox
The Python SDK is now available, providing a comprehensive interface for managing microVM-based sandboxes. Users can create, restore, and modify sandboxes, manage images and snapshots, handle volumes and mounts, and execute commands within sandboxes. The SDK includes support for SSH, metrics, logging, and secrets, along with type stubs for better developer experience.
sdk/python/microsandbox · high confidence
Introduce Python SDK with async sandbox lifecycle and management APIs
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
Introduce Ruby SDK for sandbox management
Adds the initial Ruby SDK implementation, providing a \Microsandbox\ module with builder classes (\SandboxBuilder\, \HttpBuilder\) to configure and launch sandboxes. The SDK exposes fluent APIs for setting network policies (including HTTP deny responses and proxy credentials), environment variables, labels, and resource limits, as well as a \Filesystem\ helper for reading, writing, and managing files within the sandbox environment.
sdk/ruby/lib · high confidence
Introduce Ruby extension for detached runtime jobs
The Ruby SDK now exposes a new \Microsandbox::Job\ API, allowing users to spawn and manage detached background tasks within a sandbox. This change adds methods to execute commands asynchronously, retrieve job status and logs, and attach to running jobs for data exchange, enabling long-running or background workloads without blocking the main Ruby process.
sdk/ruby/ext/microsandbox · high confidence
Introduce Rust SDK for microsandbox with lifecycle and runtime installation
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
Introduce TLS interception (MITM) for guest network traffic
The network engine now intercepts TLS connections from the guest by terminating them with per-domain certificates signed by a sandbox-specific Certificate Authority, then re-originating the connection to the real server. This enables policy enforcement and secret injection on encrypted traffic. The implementation includes automatic CA generation and persistence, a certificate cache with pre-built server configs for performance, and logic to ship the host's trusted root CAs to the guest to support corporate MITM proxies. It also handles SNI extraction, policy evaluation, and upstream connector scoping.
crates/network/lib/engine/tls · high confidence
Introduce TypeScript SDK with builder API and native bindings
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
Introduce \`microsandbox\` CLI shim for native binary execution
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
Introduce \`msb completion\` command for shell integration
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
Introduce backend-neutral snapshot API with explicit guest flush and integrity controls
The Rust SDK now exposes a unified, backend-neutral snapshot interface (\Snapshot\, \SnapshotBuilder\, \SnapshotHandle\) that abstracts away local and cloud storage differences. Users can create, open, and manage snapshots using a consistent API, with explicit control over guest filesystem flush policies (defaulting to auto-flush) and optional payload integrity recording. The API supports creating snapshots from sandboxes, opening them by ID or path, and copying archives with customizable labels and integrity settings. Verification reports provide detailed status on upper-layer and checkpoint integrity, while save options allow fine-grained control over archive composition (e.g., including parent layers, image artifacts, or specific disk layers).
sdk/rust/lib/snapshot · high confidence
Introduce cloud backend implementation for sandbox management
The SDK now includes a new \CloudBackend\ that communicates with the msb-cloud control plane over HTTP and WebSockets. This implementation enables cloud-based sandbox lifecycle operations (create, start, stop, list) via REST APIs, log streaming via Server-Sent Events, and interactive agent sessions (exec, attach, guest filesystem) over a dedicated WebSocket relay. The backend supports identity-bound agent connections, paginated resource listings, and volume management, allowing users to run and manage sandboxes in a hosted or self-hosted cloud environment using API key authentication.
sdk/rust/lib/backend/cloud · high confidence
Introduce core metrics collector library with sandbox staleness filtering and label enrichment
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
Introduce global on-disk image cache with cross-process locking
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
Introduce host-to-guest TCP/UDP port publishing
Adds the \PortPublisher\ component in \crates/network/lib/engine/ports\, which manages host-side TCP and UDP listeners that forward inbound connections and datagrams into the guest VM via smoltcp. This enables external traffic to reach services running inside the guest by binding to configured published ports, handling connection queuing, NAT mappings for UDP peers, and proper lifecycle management including draining responses and releasing resources.
crates/network/lib/engine/ports · high confidence
Introduce live secrets engine with host-scoped substitution and HTTP/2 integrity checks
The network engine now includes a new secrets subsystem that allows secrets to be rotated, removed, or have their allowed hosts updated at runtime without restarting the sandbox. Secret substitution is scoped to specific header fields and destination hosts, ensuring secrets are only injected where explicitly permitted. The handler also enforces structural integrity on HTTP/2 HPACK header blocks to prevent decoder panics from truncated input, and supports scanning for placeholders in HTTP/1 and HTTP/2 request bodies and headers.
crates/network/lib/engine/secrets · high confidence
Introduce live shared-memory metrics registry
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
Introduce lock-free netstack backend and device for smoltcp integration
This change adds the core networking engine components in \crates/network/lib/engine/netstack\, including \SmoltcpBackend\ (bridging libkrun's NetWorker to smoltcp via lock-free queues), \SmoltcpDevice\ (implementing smoltcp's device API with a single-frame slot design), and the \poll.rs\ event loop (handling frame classification, TCP socket creation, DNS interception, and proxy coordination). These files establish the foundational architecture for guest network traffic processing, replacing or supplementing previous implementations with a thread-safe, zero-copy frame passing mechanism between the guest, smoltcp, and proxy tasks.
crates/network/lib/engine/netstack · high confidence
Introduce metrics-collector library with OTLP and stdout exporters
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
Introduce microsandbox-agentd as the guest-side init and agent daemon
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
Introduce msb-metrics sibling-process metrics collector
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
Introduce presence-aware configuration patching via derive macro
A new \ConfigPatch\ derive macro is available for generating sparse, presence-aware configuration patches. This allows users to update configuration structures by specifying only the fields that have changed, leaving absent fields to retain their existing or default values. The macro supports nested struct updates, optional fields, and collection merging (via \merge\ or \merge\_with\ attributes), enabling precise, incremental configuration overlays without replacing entire objects.
packages/microsandbox-types/macros · high confidence
Introduce storage usage reporting and runtime cache pruning
The storage module now exposes APIs to inspect disk usage across images, snapshots, sandboxes, volumes, and memory caches, and provides a mechanism to prune unused runtime RAM. Users can query detailed storage statistics (counts, logical/allocated bytes, reclaimability) for managed objects and trigger cleanup of the local memory cache, with remote backends explicitly unsupported for these operations.
sdk/rust/lib/storage · high confidence
Introduce transport-agnostic microsandbox agent client libraries for Rust and TypeScript
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
Introduces Python and Ruby SDKs with structured error handling and managed job APIs
The microsandbox product now includes official SDKs for Python and Ruby, providing developers with typed interfaces to manage sandbox lifecycles and background processes. The Python SDK introduces a comprehensive exception hierarchy in \errors.py\ (covering runtime, network, and snapshot states) and a \setup.py\ module for automatic host runtime resolution and installation. Both SDKs expose a managed job API (\jobs.py\ / \jobs.rb\) that allows users to execute detached commands, stream logs, and track execution states with structured data classes. This enables programmatic control over sandboxed workloads with robust error reporting and lifecycle management.
microsandbox · high confidence
New DNS domain filtering example
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
New Rust SDK agent communication and logging infrastructure
The Rust SDK now includes a new agent communication layer (\sdk/rust/lib/agent\) featuring \AgentClient\ for connecting to sandbox relays and \AgentBridge\ as an FFI-friendly façade for non-Rust bindings, along with a new logging subsystem (\sdk/rust/lib/logs\) that provides \LogCursor\ for stream resumption and \SandboxLogger\ for reading and following sandbox logs. Additionally, the SDK's local backend database layer (\sdk/rust/lib/db\) has been introduced with migration fixtures and configuration fixtures for versions v0.6.0 through v0.6.18 to support catalog and sandbox state management.
sdk/rust/lib/sandbox · high confidence
New Rust SDK examples for networking, secrets, and volumes
Added Rust example programs demonstrating the new embeddable SDK's capabilities, including basic networking (DNS, HTTP), port publishing, secret injection with TLS interception, custom TLS bypass rules, OCI image loading, and named persistent volumes shared across sandboxes.
(repo-wide) · high confidence
New Rust SDK setup library for cross-platform host diagnosis and runtime installation
The \sdk/rust/lib/setup\ module introduces a new Rust library that provides cross-platform host readiness checks and runtime installation capabilities. It includes platform-specific diagnostics for Linux (KVM and CPU virtualization flags), macOS (Apple silicon requirement), and Windows (Hypervisor Platform availability), along with a unified \msb doctor\-style diagnosis engine that reports pass/fail/warn states and offers safe, auto-runnable fixes. The library also handles runtime resolution and installation from release downloads, embedded archives, or local directories, with SHA-256 verification and version detection from ELF, Mach-O, and PE executables without running them.
sdk/rust/lib/setup · high confidence
New Rust example demonstrating body-injected secrets with TLS interception
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
New Rust example demonstrating sandbox lifecycle convergence and concurrency safety
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
New Rust example for attaching disk image volumes
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
New Rust example for file-based sandbox snapshots
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
New Rust example for interactive shell attachment
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
New Rust example for reading sandbox logs with source filtering and tailing
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
New Rust example for streaming sandbox metrics
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
New Rust examples for filesystem streaming and init handoff
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
New Rust runtime library for sandbox lifecycle and process management
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. Also in this area: Improved reliability for interrupted sandbox creation and clearer database schema error messages; Backend policy enforcement and snapshot restore inspection; Network and secret denials now return structured JSON responses by default; Fixes bulk operation failure handling and preserves legacy runtime endpoints; Expose sandbox terminal exit outcomes and restrict new network limits.
sdk/rust/lib/runtime · high confidence
New TypeScript SDK examples for sandbox lifecycle, networking, and storage
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
New TypeScript SDK policy API for network access control
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
New TypeScript type definitions for cloud, domain, and snapshot APIs
The \packages/microsandbox-types/typescript/src\ package now exports generated TypeScript types for the microsandbox platform. This includes \cloud.ts\ defining request structures for creating sandboxes from OCI images, bind mounts, or disk images; \domain.ts\ specifying core types such as environment variables, security profiles, mount options, secret substitution rules, and network policies; \snapshot.ts\ detailing snapshot manifests, scopes, and state variants; and \size.ts\ providing branded size helpers (KiB, MiB, GiB, TiB) for resource specifications.
packages/microsandbox-types/typescript/src · high confidence
New automation and Windows support scripts for release, installation, and documentation
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
New checkpoint infrastructure with filesystem state limits and disk layer optimization
This change introduces a new checkpoint subsystem in \crates/image/lib/checkpoint\ that manages immutable composite-checkpoint manifests, local content storage, and disk layer compaction. It adds a configurable filesystem state budget (\fs\_state\_limit\) to restrict virtio-fs backend state during checkpoint capture and validation, ensuring restore operations stay within resource bounds. The subsystem also introduces an \AdmittedDiskLayers\ cache to optimize reuse of verified immutable disk files by keeping file handles alive for hash reuse, and provides utilities for compacting disk layer chains into standalone qcow2 or raw images. Additionally, it includes strict validation for qcow2 images to ensure they are standalone (no implicit backing or external data files) and supports portable checkpoint closure resolution with architecture compatibility checks.
crates/image/lib/checkpoint · high confidence
New cloud wire contracts and TypeScript bindings for sandbox and snapshot operations
The Rust types crate now generates checked TypeScript bindings for the cloud API, covering sandbox creation (OCI, bind, disk image, and disk snapshot sources), cloud secrets, and snapshot operations. These wire contracts introduce structured request shapes with explicit source tagging, snake\_case enum variants for the wire format, and robust backward compatibility deserialization that accepts legacy untagged \image\ and \disk\_snapshot\_ref\ fields from previous versions. Users benefit from stricter validation of known fields, support for future-proofing via unknown-field ignoring, and consistent serialization that enables independent evolution of SDK and server releases.
packages/microsandbox-types/rust/lib · high confidence
New database entity models for sandbox lifecycle, resource allocation, and image management
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
New fluent builder API for network configuration and policy
The network configuration model now exposes a fluent builder API (NetworkBuilder, HttpBuilder, DnsBuilder, etc.) that allows users to programmatically construct and validate network settings, policies, and secret injection rules. This includes support for configuring HTTP denial responses (with JSON format and custom messages), DNS interception settings, TLS interception, and outbound proxy credentials. The builder enforces validation at build time, ensuring that domain names, IP addresses, CIDRs, and rate limits are correctly formatted before the configuration is applied.
crates/network/lib/model · high confidence
New generic protocol client and ICMP relay capabilities
This release introduces a generic framed protocol client library (packages/protocol-client/rust) that manages shared connections, ID routing, and message encoding/decoding, alongside a new ICMP engine (crates/network/lib/engine/icmp) that relays ICMP echo requests and synthesizes ICMP error frames (such as Packet Too Big) for guests. Additionally, a new agentd binary validator (crates/filesystem/lib/agentd/format.rs) ensures that uploaded agent executables are valid 64-bit little-endian ELF files matching the target architecture.
(repo-wide) · high confidence
New image library with OCI registry support and EROFS/ext4 materialization
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
New local snapshot archive format with sparse file and incremental import support
The local snapshot backend now uses a new \.msb\ archive format (tar + zstd) that stores sparse upper-layer files as old-GNU sparse entries, reducing save cost to scale with actual written data. Importing archives now supports incremental snapshots with explicit disk and memory dependencies, allowing batch imports to resolve shared layers from existing snapshots or an external base. The system also preserves source provenance during archive copies and handles legacy archive formats for backward compatibility. Also in this area: Improved reliability for interrupted sandbox creation and clearer database schema error messages; Backend policy enforcement and snapshot restore inspection.
sdk/rust/lib/backend/local/snapshot · high confidence
New microsandbox agent protocol with typed message payloads and CBOR framing
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
New microsandbox-filesystem crate with composable backends and offline build support
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
New microsandbox-filesystem crate with embedded agentd and platform-specific backends
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
New native Rust bindings for the Node.js SDK
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
New network policy example for Rust sandboxing
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
New release packaging and smoke-test scripts for the Node SDK
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
New rootfs patching example for pre-boot filesystem modifications
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
New shared utility library for cross-platform file, process, and state management
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
Redesigned TypeScript SDK with native fluent builders and bundled binaries
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
Repository initialization with development tooling and compatibility documentation
The repository is initialized with essential development infrastructure, including \.gitignore\, \.dockerignore\, and \.gitattributes\ to manage build artifacts and line endings, alongside \.pre-commit-config.yaml\ to enforce Rust formatting, linting, and Python checks. The project also introduces \AGENTS.md\ and \COMPATIBILITY.md\, which define contribution guidelines, project structure, and detailed backward-compatibility contracts for the SDK, CLI, and runtime boundaries.
(repo-wide) · high confidence
Support for HTTP CONNECT, SOCKS4, and SOCKS5 outbound proxies
The network library now allows outbound sandbox connections to be routed through external proxies. Users can configure HTTP CONNECT proxies for TCP tunneling, SOCKS4 proxies with optional user IDs, and SOCKS5 proxies with username/password authentication. Additionally, SOCKS5 proxies now support UDP association for datagram relaying, enabling broader network traffic to be proxied through the sandbox environment. Also in this area: Python SDK adopts PyO3 0.22 API and improves secret handling in examples; CLI context command gains profile management and HTTP CONNECT proxy supports basic authentication.
crates/network/lib/proxy · high confidence
Support for loading and saving container image archives
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
Support for outbound UDP relay with fragment reassembly and proxy integration
The UDP engine now handles non-DNS UDP traffic by relaying datagrams through host sockets, including support for IPv4 and IPv6 fragment reassembly to ensure policy enforcement on complete payloads. This change introduces a bounded reassembler for fragmented UDP packets and a relay system that supports optional SOCKS5 outbound proxies, allowing users to route UDP traffic through proxies while maintaining session limits and handling ICMP errors for path MTU discovery.
crates/network/lib/engine/udp · high confidence
Unified local and cloud backend abstraction with profile-based selection
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
Unified volume filesystem operations for local and cloud backends
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. Also in this area: Improved reliability for interrupted sandbox creation and clearer database schema error messages.
sdk/rust/lib/volume · high confidence
Architecture
Rust SDK library relocated to sdk/rust/lib with comprehensive error and module exports
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. Also in this area: Backend policy enforcement and snapshot restore inspection; Expose sandbox terminal exit outcomes and restrict new network limits.
sdk/rust/lib · high confidence
Behavioural changes
13 commits (6 fixes) modifying crates/db/lib
A change to existing behaviour in crates/db/lib — 13 commits (6 fixs), 13 files: “fix(db): read connections must not create the catalog db (\#879)”; “fix(compat): preserve cross-version sdk and runtime compatibility (\#1634)”; “fix(config): preserve caller overrides across rebuilds (\#1913)”; and 10 more (refs \#879, \#1634, \#1913, \#925, \#1982, …).
crates/db/lib · medium confidence · unverified
2 commits (1 fix) modifying crates/image/lib/tar
A change to existing behaviour in crates/image/lib/tar — 2 commits (1 fix), 3 files: “fix(cli): repair stdin, logs, init, image, and port failures (\#2030)”; “refactor(image)!: restructure image crate modules (\#795)” (refs \#2030, \#795).
crates/image/lib/tar · medium confidence · unverified
28 commits (6 fixes) modifying sdk/rust/lib/config
A change to existing behaviour in sdk/rust/lib/config — 28 commits (6 fixs), 6 files: “revert(exec): remove unreleased output backpressure (\#1875)”; “feat(config): configure deployment profile from config.json (\#1323)”; “fix(runtime): find libkrunfw through symlinks (\#1632)”; and 25 more (refs \#1875, \#1323, \#1632, \#1301, \#1324, …).
sdk/rust/lib/config · medium confidence · unverified
33 commits (12 fixes) modifying crates/filesystem/lib/backends
A change to existing behaviour in crates/filesystem/lib/backends — 33 commits (12 fixs), 139 files: “feat(filesystem): default-on mount-root symlink protection with opt-out (\#1149)”; “feat(mounts): harden volume mount options (\#832)”; “fix(filesystem): map bind mount ownership for guest users (\#839)”; and 30 more (refs \#1149, \#832, \#839, \#751, \#2032, …).
crates/filesystem/lib/backends · medium confidence · unverified
Database schema migration for microsandbox v0.6.16
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
Improved network policy enforcement and IPv6/NAT64 handling
The network engine now provides more robust and user-friendly behavior for denied connections and IPv6 environments. HTTP and HTTPS egress requests that are blocked by policy now receive a readable 403 Forbidden response (including a JSON body by default) instead of a raw connection reset, making it easier to diagnose policy issues. Additionally, the engine better supports IPv6-only or mixed environments by normalizing IPv4-mapped IPv6 addresses for consistent policy classification and correctly extracting embedded IPv4 addresses from NAT64 prefixes, ensuring that network policies apply correctly even when IPv4 endpoints are represented as IPv6.
crates/network/lib/engine · high confidence
Introduce generation-two control protocol with new runtime operations
The control protocol has been upgraded to generation two, introducing a new handshake mechanism (ControlHello/ControlWelcome) that negotiates protocol versions and limits. This change adds support for a new set of CBOR-based operations including full and disk-only checkpoint creation, direct local branch creation, resident pause/resume with guest flush policies, root disk growth, and disk compaction. Existing generation-one operations remain supported for backward compatibility, but new capabilities are only exposed to peers that negotiate generation two.
crates/protocol/lib/control · high confidence
Introduce schema-1 snapshot descriptor with v0.6.6 migration support
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
Introduce structured CLI command groups and self-management commands
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. Also in this area: CLI context command gains profile management and HTTP CONNECT proxy supports basic authentication; JSON format for HTTP deny responses and granular deny messages; Add TCP connection limits and simplify storage usage output.
crates/cli/bin · high confidence
Network library module organization and public API re-exports
The network library has been reorganized to clearly separate configuration models from the optional packet-processing engine. The \model\ module is always available for SDK-side configuration, while the \engine\ feature (enabled for the \msb\ runtime) adds packet processing, relays, DNS forwarding, policy enforcement, TLS interception, and port publishing. The crate now explicitly re-exports key components such as proxy builders (HTTP CONNECT, SOCKS4, SOCKS5 with credentials), DNS and policy models, and engine-specific types like TCP/UDP connections, ICMP relays, and port publishers, making these capabilities directly accessible to consumers of the library.
crates/network/lib · high confidence
New OCI registry client with builder pattern and platform resolution
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
Overhauled CI infrastructure with hardened runners, safer release pipelines, and comprehensive test coverage
The CI system has been significantly restructured to improve reliability, security, and maintainability. Self-hosted runner provisioning is now automated via \provision-runners.sh\, which enforces strict security by revoking legacy Docker/sudo privileges and isolating each runner in its own unprivileged user account. Disk management is hardened with \clean-runner-disk.sh\ and \runner-storage.py\, which prevent accidental deletion of the active checkout and enforce cache size limits to avoid runner exhaustion. The release pipeline is safer and more robust: npm publishing now uses \publish-npm-package.mjs\ to detect and resume partially published packages, enforces npm provenance, and strictly orders dependency publication to handle registry indexing lag. Release notes are now automatically categorized by commit type via \release-notes.cjs\, with specific filtering to exclude automated sync PRs. Additionally, new test suites (\test\_install.py\, \test\_bump\_version.py\, \test\_publish\_crates.py\, etc.) provide regression coverage for the installer, version bumping logic, and release ordering, ensuring these critical paths remain stable.
scripts/ci · high confidence
Preserved cross-version SDK and runtime compatibility for sandbox configurations
The local SQLite database now safely handles downgrades and upgrades of sandbox configurations across SDK versions 0.5.0 through 0.7.6. The new compatibility layer in \crates/db/lib/compat\ automatically rewrites persisted JSON to match the target runtime's expected schema, ensuring that critical settings like CPU counts, mount types, and image references are preserved without data loss. It also strictly enforces runtime constraints, rejecting configurations that use secret header-field substitution scopes or global passthrough defaults if the target runtime version does not support them, preventing silent misconfigurations during version transitions.
crates/db/lib/compat · high confidence
Redesigned TypeScript SDK with native NAPI bindings and builder API
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
Redesigned local sandbox lifecycle with platform-specific exit barriers
The local sandbox backend has been restructured into dedicated modules (create, stop, process\_exit) to enforce stricter lifecycle management. The new create flow handles image pulling, rootfs preparation, and process spawning through a unified entry point with robust cleanup guards. Stop operations now utilize platform-specific exit barriers (pidfd on Linux, kqueue on macOS) to reliably detect runtime teardown without relying on potentially recycled PIDs, ensuring safe ownership release and preventing stale state during shutdown.
sdk/rust/lib/backend/local/sandbox · high confidence
Refactored local backend into modular components with improved catalog and path handling
The local backend implementation has been restructured into distinct modules to improve separation of concerns and reliability. A new \control\_lookup\ module provides read-only, race-free lookup for live sandbox control targets, ensuring that runtime restarts do not redirect control requests to stale processes. Database interactions are now centralized in \database.rs\, which enforces strict migration locking and schema validation to prevent catalog corruption during upgrades. Path resolution logic has been extracted into \host\_paths.rs\, which now explicitly resolves relative host paths to absolute ones at configuration time and validates bind mount roots to detect symlink issues early, before sandbox creation. These changes collectively enhance the stability of the local backend by isolating state management and improving error reporting for configuration issues.
sdk/rust/lib/backend/local · high confidence
Robust image cleanup with crash recovery
The Rust image library now includes a durable cleanup mechanism that prevents data loss or corruption during interrupted image removal operations. By introducing a deletion journal and hard-link-based validation, the system ensures that image files are only removed if they have not been replaced by a new publication in the interim, and it automatically recovers from crashes that occur during the cleanup process. This change improves reliability for users managing local image caches, ensuring that active images are never accidentally deleted and that partial cleanup operations are safely retried.
sdk/rust/lib/image · high confidence
Ruby SDK introduces typed exception classes with machine-readable error codes
The Ruby SDK now provides a structured error hierarchy where every sandbox, image, volume, snapshot, and backend operation failure raises a specific exception class (e.g., \SandboxNotFoundError\, \ExecFailedError\, \SnapshotIntegrityError\) instead of generic errors. Each exception includes a stable, machine-readable \code\ attribute (such as \sandbox-not-found\ or \exec-failed\) to allow precise error handling. Specialized errors like \UnsupportedError\ and \SnapshotSourceRecoveryError\ carry additional context attributes (e.g., \operation\, \hint\, \checkpoint\_path\) to help users understand why an operation failed and how to resolve it, mirroring the error handling patterns of the Python and Go SDKs.
sdk/ruby/lib/microsandbox · high confidence
Rust control client introduces generation-2 CBOR parity and verified runtime identity
The Rust control client now supports generation-2 operations (CreateCheckpoint, CreateDiskCheckpoint, CreateBranch, PauseRuntime, ResumeRuntime, GetPauseState, GrowRootDisk, and CompactDisks) alongside the existing generation-1 set, using automatic discovery to select framed CBOR or legacy JSON. It adds a VerifiedControlConnector trait that requires the runtime owner to verify peer identity and OS birth tokens on every dial and before each operation, invalidating the handle if continuity fails rather than silently retargeting requests. The client also provides a lossless JSON value parser that preserves original number tokens and rejects duplicate keys, and ensures that rejected legacy operations include the peer's original message in the error details.
packages/control-client · high confidence
Structured boot and exec error diagnostics with actionable hints
The CLI now renders structured boot-stage and execution failures with clear, actionable hints. When a sandbox fails to start, the CLI reads the \boot-error.json\ record and displays a styled error block indicating the failure stage (e.g., mount, network, image) along with specific remediation steps, such as checking host path permissions or ensuring the image is pulled. Similarly, when a command fails to execute inside the sandbox, the CLI provides targeted hints based on the failure type (e.g., suggesting to check PATH for \NotFound\ or permissions for \PermissionDenied\). These changes improve troubleshooting by replacing generic error messages with stage-specific guidance and consistent log pointers.
crates/cli/lib · high confidence
Support for resizing legacy ext4 upper disk images
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
Fixes
10 commits (6 fixes) fixing crates/cli/lib/commands/self\_cmd
A fix in crates/cli/lib/commands/self\_cmd — 10 commits (6 fixs), 6 files: “fix(sandbox): recover interrupted creation cleanup (\#1918)”; “fix(compat): preserve cross-version sdk and runtime compatibility (\#1634)”; “feat(network): scope secret substitution to specific header fields (\#1639)”; and 6 more (refs \#1918, \#1634, \#1639, \#1913, \#1707, …).
_crates/cli/lib/commands/self\cmd · medium confidence · unverified
Improved sandbox creation reliability and snapshot support
The sandbox creation process now includes robust cancellation cleanup to prevent resource leaks and ensure consistent state when operations are interrupted or fail during startup. Additionally, the system now supports restoring sandboxes from disk-only snapshot archives, allowing for more flexible recovery options from saved states. Also in this area: Improved reliability for interrupted sandbox creation and clearer database schema error messages.
sdk/rust/lib/backend/local/sandbox/create · high confidence
Preserve cross-version SDK and runtime compatibility in test support
The test support module now includes a custom JSON decoder that rejects duplicate object keys to prevent silent policy overwrites and avoid exposing secret values in error messages. It also implements a preservation check that ensures no fields are dropped or altered during configuration migration, validating that persisted sandbox configurations from older SDK versions (0.6.0 through 0.6.18) decode correctly without losing resources, mounts, or unknown fields.
_sdk/rust/lib/test\support · high confidence
TCP connection handling and policy denial responses
The TCP engine now manages connections through a dedicated tracker that relays data between the guest's smoltcp sockets and host-side proxy tasks. When egress policy denies a connection, the system accepts the TCP handshake for HTTP and HTTPS ports to deliver a 403 Forbidden response instead of a hard reset, improving the guest's experience. It also implements IPv4 fallback when IPv6 connections stall, ensuring connectivity is maintained even if one address family is unavailable. Additionally, the engine now drains pending TCP responses before closing connections and rejects truncated HPACK blocks to prevent decoding errors.
crates/network/lib/engine/tcp · high confidence
Test coverage
Added Node.js SDK smoke tests; Added fuzzing target for local snapshot archive unpacking; Added integration and unit tests for the Ruby Microsandbox SDK; Added integration tests for CLI exec, sandbox lifecycle, and streaming features; Added integration tests for network port publishing and TCP connectivity; Added integration tests for the msb-metrics CLI and OTLP exporter; Added protocol conformance and legacy-compatibility tests; Added smoke tests for root disk growth, branching, and checkpointing; Added tests for LocalBackend path resolution and lifetime; Added tests for SQLite lock preservation and control session identity; Added tests for metrics lookup database identity retention and multi-registry validation; Added tests for network module path aliases and secret denial behavior; Added tests for sandbox config patching and overlay behavior; Added unit tests for the redesigned TypeScript SDK; Expanded Python SDK test coverage for configuration validation and serialization; Expanded Rust SDK test coverage for API compatibility, lifecycle, and network policies; Go SDK integration test suite; New test infrastructure for isolated microsandbox integration tests; Python SDK integration test suite added.
Dependencies
Microsandbox v0.6.18 release with dependency updates
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
Updated libkrunfw vendor submodule
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 cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 50 → 68 (+18.2)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 75 → 61 (-13.8)
- Architecture 84 → 87 (+2.9)
- Maturity 67 → 72 (+4.5)
- Readiness 74 → 78 (+3.3)
- Security 24 → 78 (+53.9)
- Domain Modelling 100 → 100 (+0.0)
- Event Sourcing 100 → 100 (+0.0)
- Performance 70 → 70 (+0.0)
Resolved (237)
- BatchSmoke.exercise (cognitive 47) (scripts/smoke/cli/branch-batch.py)
- BatchSmoke.exercise (cyclomatic 24) (scripts/smoke/cli/branch-batch.py)
- Change coupling: common.rs ↔ lib.rs (crates/cli/lib/commands/common.rs)
- Duplicated block (10 lines × 2) (crates/metrics/lib/snapshot.rs)
- Duplicated block (10 lines × 2) (sdk/node-ts/native/sandbox.rs)
- Duplicated block (10 lines × 2) (sdk/node-ts/native/ssh.rs)
- Duplicated block (10 lines × 2) (sdk/python/src/helpers.rs)
- Duplicated block (10 lines × 2) (sdk/python/src/sandbox.rs)
- Duplicated block (10 lines × 2) (sdk/python/src/sandbox.rs)
- Duplicated block (10 lines × 3) (sdk/rust/lib/backend/local/sandbox/create.rs)
- Duplicated block (10 lines × 3) (sdk/rust/lib/backend/local/snapshot/archive.rs)
- Duplicated block (10–12 lines × 2) (crates/filesystem/lib/backends/dualfs/create_ops.rs)
- Duplicated block (10–13 lines × 2) (crates/filesystem/lib/backends/passthroughfs/unix/xattr_ops.rs)
- Duplicated block (11 lines × 2) (crates/cli/lib/tree.rs)
- Duplicated block (11 lines × 2) (crates/runtime/lib/checkpoint/disk.rs)
- Duplicated block (11 lines × 2) (crates/runtime/lib/checkpoint/disk.rs)
- Duplicated block (11 lines × 2) (crates/runtime/lib/client/ipc.rs)
- Duplicated block (11 lines × 2) (sdk/node-ts/native/ssh.rs)
- Duplicated block (11 lines × 2) (sdk/rust/lib/backend/local/sandbox/mod.rs)
- Duplicated block (11 lines × 2) (sdk/rust/lib/backend/local/snapshot/restore.rs)
- …and 217 more
New (804)
- Duplicated block (10 lines × 2) (crates/filesystem/lib/backends/passthroughfs/unix/mobility.rs)
- Duplicated block (10 lines × 2) (crates/runtime/lib/runner/cpu/planner.rs)
- Duplicated block (10 lines × 2) (sdk/go/native/src/lib.rs)
- Duplicated block (10 lines × 2) (sdk/node-ts/native/sandbox_handle.rs)
- Duplicated block (10 lines × 2) (sdk/python/src/sandbox.rs)
- Duplicated block (10 lines × 2) (sdk/python/src/sandbox.rs)
- Duplicated block (10 lines × 3) (crates/agentd/lib/session.rs)
- Duplicated block (10 lines × 3) (sdk/rust/lib/backend/local/snapshot/archive.rs)
- Duplicated block (10 lines × 4) (crates/filesystem/lib/backends/dualfs/create_ops.rs)
- Duplicated block (10–11 lines × 2) (crates/cli/lib/commands/modify.rs)
- Duplicated block (10–11 lines × 3) (crates/filesystem/lib/backends/dualfs/remove_ops.rs)
- Duplicated block (11 lines × 2) (crates/agentd/lib/session.rs)
- Duplicated block (11 lines × 2) (crates/cli/lib/tree.rs)
- Duplicated block (11 lines × 2) (crates/image/lib/ext4/rootfs.rs)
- Duplicated block (11 lines × 2) (crates/runtime/lib/checkpoint/disk.rs)
- Duplicated block (11 lines × 2) (crates/runtime/lib/checkpoint/disk.rs)
- Duplicated block (11 lines × 2) (crates/runtime/lib/checkpoint/layout.rs)
- Duplicated block (11 lines × 2) (crates/runtime/lib/client/ipc.rs)
- Duplicated block (11 lines × 2) (sdk/go/native/src/lib.rs)
- Duplicated block (11 lines × 2) (sdk/python/src/sandbox.rs)
- …and 784 more
Changes since last survey
- 36 commits — 20 feature/other, 16 fixes
By area
- sdk/rust — 7 commits
- .github/workflows — 5 commits
- (root) — 4 commits
- examples/typescript — 4 commits
- crates/filesystem — 3 commits
- sdk/node-ts — 3 commits
- crates/db — 2 commits
- crates/network — 2 commits
- docs/sdk — 2 commits
- scripts/ci — 2 commits
- crates/cli — 1 commit
- docs/getting-started — 1 commit
Notable commits
- fix: fix(cli): repair stdin, logs, init, image, and port failures (#2030)
- fix: fix(cli): resolve bare host copy destinations against the current dir (#1936)
- fix: fix(cloud): repair SDK cleanup and CLI onboarding (#1970)
- fix: fix(deps): bump msb_krun to 0.1.43 for Windows 10 (#2007)
- fix: fix(deps): bump msb_krun to 0.1.44 (#2017)
- fix: fix(deps): update msb_krun to 0.1.45 and libkrunfw (#2033)
- fix: fix(filesystem): follow host-side renames on Windows bind mounts (#1926)
- fix: fix(filesystem): skip Windows reparse points in directory listings (#2012)
- fix: fix(filesystem): translate guest sparse seek modes on macos (#1831)
- fix: fix(release): enable keyring in cli builds (#1976)
- fix: fix(release): prepare 0.7.13 homebrew repair (#1991)
- fix: fix(release): recover existing tags with supported macOS runners (#1987)
- fix: fix(sandbox): recover interrupted creation cleanup (#1929)
- fix: fix(sdk/node): validate kill and connect timeouts before calling native (#1944)
- fix: fix(ssh): preserve failed command outcomes (#2011)
- fix: fix(storage): recover legacy sandbox storage safely (#2022)
- change: Ci/lint all targets (#1982)
- change: Merge commit from fork
- change: Merge commit from fork
- change: chore(deps): Bump the "dependencies" group with 2 updates across multiple ecosystems (#1961)
- …and 16 more
Architecture
- Unchanged — 0 containers · 2 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
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.
About this page
- The score is its most recent published measurement, taken on 14 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 28bdced502513f46b2372dade590ba7e91466242 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-e1a3b69fc8ee.