Skip to content

v0.1.2

Latest
Latest

Choose a tag to compare

View all tags
@lxcshine lxcshine released this 25 Jun 16:32
· 27 commits to master since this release
v0.1.2
a233f90
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release Notes

NexusBox Sandbox v0.1.2

Release date: 2026-06-26

This release delivers Phase 2 (Developer Experience): four协同 features that bring NexusBox from "sandbox that runs" to "sandbox developers actually want to use" — snapshot/restore, multi-language runtimes, hot-reload configuration, and workspace isolation. Alongside the features, this release adds project visualizations, a self-contained HTML test report, and two stdio-driven MCP availability scripts that catch a real Go/Java gap in the MCP entrypoint.

Highlights

  • Snapshot / Restore (VSS) — Return a corrupted workspace to the last good state without restarting the service. Backend abstraction auto-selects Windows VSS (vssadmin) on Windows and a filesystem mirror elsewhere, with graceful fallback when VSS is unavailable.
  • Multi-language runtime (Python / Node / Go / Java) — Cover mainstream AI programming scenarios. Both the Gateway REST entrypoint and the MCP stdio entrypoint now compile and run all four languages.
  • Hot-reload configuration — Update sandbox runtime configuration (concurrency, timeouts, endpoints) without restarting. A dependency-free polling watcher applies new config to the RuntimeManager live, inheriting empty fields from defaults so partial updates are safe.
  • Workspace isolation (multi-project parallelism) — Multiple AI sessions no longer collide. Workspace.ResolvePath confines every file path to the session's root, rejecting ../ and re-rooting absolute paths; resource quotas cap CPU, memory, disk, and file count per workspace.
  • Visual test report — A self-contained HTML report (inline SVG charts, no external deps) summarizes the latest MCP availability run at a glance.

New Features

Snapshot / Restore (VSS)

  • Introduce SnapshotBackend interface with three implementations: vssBackend (Windows Volume Shadow Copy), filesystemBackend (cross-platform hardlink + mirror with byte-copy fallback), and containerdBackend (Linux CRIU checkpoint, retained for compat).
  • Auto-select backend by OS; allow injection of a custom backend for tests.
  • Track per-snapshot metadata (source path, backend, checksum, created time) and prune by age.
  • RestoreSnapshot reproduces the source tree from the snapshot directory into the target path; an empty target reuses the original source path recorded in metadata.

Multi-Language Runtime

  • Extend CodeService (Gateway entrypoint) with executeGo (temp module + go run) and executeJava (class-name normalization to Main, javac + java).
  • Add language aliases (golang, js, node, python3) and a unified Execute dispatcher.
  • Align the MCP code_run tool with the Gateway: add go and java branches alongside python and nodejs.

Hot-Reload Configuration

  • Add config.Watcher, a cross-platform polling watcher (no fsnotify dependency) that tracks file mtimes and notifies registered Reloader implementations on change.
  • Define Reloader interface: Reload(ctx, newConfig) error with the contract that a rejected config leaves the old one in effect.
  • RuntimeManager implements Reloader: validates new concurrency/timeout/endpoint values, falls back to previous values on rejection, and inherits empty endpoint fields from defaults.

Workspace Isolation

  • Add Workspace struct with isolated Root, DataDir, TmpDir, CacheDir, and a Quota (CPU, memory, disk, file count).
  • ResolvePath is the core isolation primitive: strips volume/absolute prefixes, cleans the path, and rejects any result that escapes Root via .. — so a session bound to workspace A cannot reach workspace B's files.
  • Add WorkspaceManager for create/list/delete with owner-session binding and arbitrary labels.

Project Visualizations

  • Add 6 chart generators under scripts/visualizations/ (MCP tools distribution, startup benchmark, feature radar, concurrency throughput, multi-language benchmark, security layers) with a shared flat theme and a one-shot gen_all.py runner.
  • Embed the charts in both READMEs in a 2×3 grid with one-line captions.

MCP Availability Checks & HTML Report

  • Add scripts/check_mcp_availability.ps1 — drives nexusbox-mcp.exe over stdio, asserts the MCP initialize handshake and that tools/list returns all 18 tools.
  • Add scripts/check_mcp_tools.ps1 — exercises shell_exec, file_write+file_read, code_run across Python/Node/Go/Java, and the path-traversal guard; expects PASS: 9 FAIL: 0.
  • Add scripts/generate_test_report.py — produces a self-contained docs/test-report.html with inline SVG donut/stacked-bar charts, a language result grid, and a bug-found-and-fixed card.

Bug Fixes

fix(mcp): code_run did not support Go or Java

The MCP entrypoint pkg/mcp/code_server.go only handled python and nodejs in its language switch, returning Unsupported language: go despite Phase 2 having extended the Gateway CodeService with Go and Java. The two entrypoints were not synchronized. Fixed by adding go (go run) and java (javac + java, public class normalized to Main) branches to the MCP dispatcher, aligning it with the Gateway. All four languages now pass the availability check.

fix(snapshot): hardlinks caused snapshots to mutate with source

The filesystem backend originally created snapshots using hardlinks, which share inodes between source and snapshot. Editing a source file after snapshotting therefore changed the snapshot's content, breaking the "return to last good state" guarantee. Fixed by copying bytes on create instead of hardlinking, ensuring snapshot independence. Checksum verification was added to detect any later drift.

fix(migration): RestoreSnapshot call missing the targetPath argument

RestoreSnapshot was widened to a 4-argument signature (ctx, snapshotID, sandboxID, targetPath) but the migration manager still called it with 3 arguments, causing a compile error. Fixed by passing an empty targetPath so the restore reuses the source path recorded in the snapshot metadata.

fix(workspace): absolute paths were rejected instead of re-rooted

The workspace confinement design intends to re-root absolute paths inside the workspace, but the initial implementation rejected them outright. Fixed ResolvePath to strip the volume/absolute prefix and join the remainder onto Root, then guard the final result with filepath.Rel to ensure it stays inside Root.

fix(sandbox): Windows Job Object CPU rate-control structure length

JOBOBJECT_CPU_RATE_CONTROL_INFORMATION was laid out with incorrect alignment, producing ERROR_BAD_LENGTH (0x18) from SetInformationJobObject. Fixed by sizing the struct to 8 bytes (ControlFlags + CpuRate). A conflicting JOB_OBJECT_LIMIT_AFFINITY flag that caused ERROR_INVALID_PARAMETER was also removed, and the API call order was corrected.

Testing

  • All Phase 2 packages pass go test ./... with zero failures; no regressions in existing packages.
  • A new integration test test/integration/phase2_integration_test.go verifies the four features协同 in a real scenario: two parallel AI sessions, multi-language execution, snapshot/restore (with VSS gracefully falling back to filesystem on non-admin Windows), and hot-reload taking effect without restart.
  • Two stdio-driven PowerShell scripts drive the actual nexusbox-mcp.exe binary the same way Trae does, asserting PASS: 9 FAIL: 0 across shell/file/multi-language/security.

Test & Script Files Added

File Purpose
pkg/snapshot/manager_test.go Snapshot create/restore, backend selection, pruning
pkg/config/hotreload_test.go Watcher polling, Reloader apply/reject, file mtime detection
pkg/workspace/manager_test.go ResolvePath confinement, quotas, owner-session binding
pkg/sandbox/runtime/manager_test.go RuntimeManager reload validation and fallback
pkg/gateway/code_service_test.go Go and Java execution paths
test/integration/phase2_integration_test.go End-to-end协同 of all four Phase 2 features
scripts/check_mcp_availability.ps1 MCP handshake + tools/list availability check
scripts/check_mcp_tools.ps1 MCP tool-call e2e (shell/file/code/security)
scripts/generate_test_report.py Self-contained HTML test report generator

Breaking Changes

None for end users. RestoreSnapshot gained a targetPath argument, but this is an internal API not consumed externally. Existing sandbox configurations continue to work unchanged.

Upgrade Notes

No migration required. Phase 2 features are additive and auto-activate:

  • Snapshot — VSS is used automatically on Windows (requires admin for vssadmin); on non-admin Windows or other OSes the filesystem backend is used transparently.
  • Multi-language — ensure go, javac/java are on PATH if you want Go/Java execution; Python and Node are unchanged.
  • Hot-reload — point the watcher at your runtime config file; no new flags required.
  • Workspace isolation — WorkspaceManager is opt-in; existing single-workspace flows are unaffected.

Regenerate the test report after a run:

python scripts/generate_test_report.py
# open docs/test-report.html

Regenerate project visualizations:

python scripts/visualizations/gen_all.py

Files Changed

New Files

File Description
pkg/snapshot/vss_windows.go Windows VSS backend (vssadmin create shadow)
pkg/snapshot/vss_other.go Non-Windows VSS stub
pkg/snapshot/manager.go Snapshot manager with backend abstraction, metadata, pruning
pkg/config/hotreload.go Polling config watcher + Reloader interface
pkg/workspace/manager.go Workspace isolation with ResolvePath confinement and quotas
pkg/sandbox/runtime/manager.go RuntimeManager with hot-reload and workspace support
test/integration/phase2_integration_test.go Integration test for all four Phase 2 features
scripts/visualizations/_theme.py Shared matplotlib flat theme and brand palette
scripts/visualizations/gen_mcp_tools_chart.py MCP tools distribution donut + bar chart
scripts/visualizations/gen_performance_benchmark.py Sandbox cold-start benchmark (log-scale bar)
scripts/visualizations/gen_feature_radar.py 7-axis capability radar (NexusBox vs Docker vs demo)
scripts/visualizations/gen_concurrency_throughput.py Concurrency vs throughput line chart
scripts/visualizations/gen_multilang_benchmark.py Multi-language runtime benchmark bar chart
scripts/visualizations/gen_security_layers.py Defense-in-depth 5-ring security chart
scripts/visualizations/gen_all.py One-shot runner for all chart generators
scripts/check_mcp_availability.ps1 MCP handshake + tools/list availability check
scripts/check_mcp_tools.ps1 MCP tool-call e2e (shell/file/code/security)
scripts/generate_test_report.py Self-contained HTML test report generator
docs/test-report.html Generated HTML test report (inline SVG)
docs/phase2-integration-test.md English guide for running the Phase 2 integration test
docs/phase2-integration-test_zh.md Chinese guide for running the Phase 2 integration test

Modified Files

File Changes
pkg/gateway/code_service.go Add executeGo and executeJava, language aliases, unified Execute dispatcher
pkg/mcp/code_server.go Add Go and Java branches to code_run, align with Gateway CodeService
pkg/migration/manager.go Pass targetPath argument to widened RestoreSnapshot signature
pkg/gateway/code_service_test.go Add tests for Go and Java execution
Assets 2
Loading