Skip to content

v0.1.1

Choose a tag to compare

View all tags
@lxcshine lxcshine released this 25 Jun 05:16
· 115 commits to master since this release
v0.1.1
a489557
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.1

Release date: 2026-06-25

This release delivers the P0 and P1 priority features referenced from the CubeSandbox architecture, transforming NexusBox into a production-ready AI Agent sandbox. All new code is covered by unit tests, and a full local integration test pass confirms zero regressions.

Highlights

  • E2B SDK drop-in compatibility — existing E2B clients can switch to NexusBox by changing only the API base URL.
  • Template system — reusable sandbox configurations with four seeded defaults for common AI Agent workloads.
  • Pre-warming pool — per-template sandbox pools with TTL eviction and utilization-based auto-scaling for sub-100ms cold-starts.
  • Egress security gateway — domain allowlist/denylist, dynamic credential injection, private IP blocking, and full audit logging.
  • eBPF network policy engine — L3/L4 ingress/egress rules with auto-detection and graceful fallback to iptables.

New Features

E2B API Compatibility Layer

  • Implement full E2B SDK-compatible REST API under /e2b/v1/*.
  • Cover sandbox lifecycle (create, get, list, kill), command execution, file I/O, code execution, timeout refresh, pause/resume, logs, and stats.
  • Enable drop-in replacement for E2B Python/JS SDK, LangChain integrations, and OpenAI Agents SDK clients.

Template System

  • Add TemplateManager for reusable sandbox configurations (image, runtime, resources, env vars, working directory, restart policy).
  • Seed four default templates: python-data-science, node-fullstack, browser-automation, ai-agent-default.
  • Expose CRUD API at /v1/templates with full validation and automatic defaults.
  • Support ApplyToSandbox to inherit template defaults while preserving user-overridden fields.

Resource Pool Pre-warming

  • Add TemplatePoolManager that maintains per-template pre-warmed sandbox pools.
  • Support configurable target size, min/max bounds, TTL-based eviction, and utilization-based auto-scaling.
  • Track detailed statistics: total created, total reused, hit rate, average create/reuse latency.

Egress Security Gateway

  • Intercept outbound HTTPS traffic from sandboxes via reverse proxy.
  • Enforce domain allowlist/denylist with wildcard subdomain matching (e.g., *.openai.com).
  • Inject credentials dynamically via CredentialProvider interface (supports Vault and other secret backends).
  • Block private IP ranges (loopback, private, link-local) to prevent SSRF.
  • Audit all outbound requests with URL, method, status code, bytes sent/received, and duration.
  • Expose policy management API at /v1/egress/policies, audit log at /v1/egress/audit, and stats at /v1/egress/stats.

eBPF Network Policy Engine

  • Add pluggable Engine with three backends: EBPFBackend (production), IPTablesBackend (fallback), NoopBackend (testing).
  • Support L3/L4 ingress/egress rules with port ranges and protocol filtering (tcp, udp, icmp).
  • Auto-detect eBPF availability on Linux with graceful fallback to iptables on unsupported kernels.
  • Validate CIDRs and enforce default-deny policies per sandbox.
  • Expose policy CRUD and statistics via thread-safe methods.

Internal Helpers

  • Add ShellService.ExecSync for synchronous command execution used by the E2B compatibility layer.
  • Add FileService.ReadFile and FileService.WriteFile for synchronous file I/O with path traversal protection and atomic writes.
  • Add CodeService.ExecuteCode for synchronous Python/Node.js code execution.

Bug Fixes

fix(egress): audit log drop count underflow when maxSize < 10

The AuditLog.Append method computed dropCount = maxSize / 10, which evaluated to 0 for small log sizes, preventing any entries from being dropped when the log was full. This caused the log to grow unboundedly. Fixed by enforcing a minimum drop count of 1.

fix(egress): policy and audit API routes returned 502

The egress gateway's HTTP server handler was bound exclusively to handleRequest (the proxy handler), so requests to /v1/egress/policies, /v1/egress/audit, and /v1/egress/stats were proxied instead of handled by the policy API. Fixed by routing requests with the /v1/egress/ prefix to Gateway.ServeHTTP.

fix(code): int32 to int type mismatch in ExecuteCode

The CodeService.ExecuteCode method passed an int32 timeout directly to CodeExecuteRequest.Timeout (which expects int), causing a compile error. Fixed by explicitly casting int(timeoutSec).

fix(e2b): undefined metav1.ObjectMeta in e2bObjectMeta

The e2bObjectMeta helper returned an anonymous struct instead of metav1.ObjectMeta, causing a compile error. Fixed by importing metav1 and returning the correct type.

Testing

  • Add 64 new unit test cases across 5 new test files, covering all P0/P1 features.
  • All 16 packages pass go test ./... with zero failures.
  • Local integration test confirms all live API endpoints respond correctly: templates CRUD, E2B compatibility, egress policy/audit/stats, shell exec, code execute, and file list.

Test Files Added

File Cases Coverage
pkg/template/manager_test.go 13 CRUD, defaults, idempotent seed, ApplyToSandbox
pkg/network/ebpf/engine_test.go 11 Policy validation, CIDR validation, backends, stats
pkg/network/egress/gateway_test.go 16 Domain matching, private IP, audit log, credentials
pkg/sandbox/runtime/template_pool_test.go 10 Register, acquire, release, recycle, stats
pkg/gateway/e2b_service_test.go 14 Routes, health, templates, sandbox lifecycle

Breaking Changes

None. All new APIs are additive and do not affect existing endpoints.

Upgrade Notes

No migration required. Start the dev server with the new -egress-port flag (default 8082) to enable the egress gateway. Set it to 0 to disable.

go run ./cmd/sandbox-dev/main.go \
  -port=8080 \
  -mcp-port=8079 \
  -egress-port=8082 \
  -workspace="$PWD"

Files Changed

New Files

File Description
pkg/gateway/e2b_service.go E2B SDK-compatible REST API layer
pkg/gateway/template_service.go Template CRUD REST API service
pkg/template/manager.go Sandbox template manager with seeded defaults
pkg/sandbox/runtime/template_pool.go Template-aware pre-warming pool manager
pkg/network/egress/gateway.go Egress security gateway with credential injection
pkg/network/egress/policy.go Egress policy management API handler
pkg/network/ebpf/engine.go eBPF network policy engine with iptables fallback
pkg/template/manager_test.go Unit tests for template manager
pkg/network/ebpf/engine_test.go Unit tests for network policy engine
pkg/network/egress/gateway_test.go Unit tests for egress gateway
pkg/sandbox/runtime/template_pool_test.go Unit tests for template pool manager
pkg/gateway/e2b_service_test.go Unit tests for E2B compatibility layer

Modified Files

File Changes
pkg/gateway/gateway.go Wire TemplateService and E2BService into gateway, add routes and accessors
pkg/gateway/shell_service.go Add ExecSync method for synchronous command execution
pkg/gateway/file_service.go Add ReadFile and WriteFile synchronous helpers
pkg/gateway/code_service.go Add ExecuteCode method, fix int32 to int type cast
cmd/sandbox-dev/main.go Integrate template manager, egress gateway, and network policy engine
Assets 2
Loading