How alibaba/jvm-sandbox works
This repository is a JVM attach-time instrumentation platform rather than a conventional application. Its architecture is centered on a split between:
1. the target JVM application being inspected,
2. the sandbox core loaded into that JVM,
3. isolated extension modules loaded on demand,
4. a tiny bootstrap bridge in the bootstrap classloader.
High-level runtime shape
The system is designed to be attached to an already running Java process. The attach entrypoint is the sandbox-agent module, which loads the core into the target JVM without requiring an application restart. Once attached, the core runs inside the target process and exposes management and inspection capabilities.
The main runtime stack is:
• sandbox-agent — agent bootstrap and classloader setup
• sandbox-core — instrumentation engine, module manager, server, runtime services
• sandbox-spy — bootstrap-resident bridge used by instrumented bytecode
• sandbox-api / sandbox-common-api — module-facing contracts and shared abstractions
• sandbox-debug-module and sandbox-mgr-module — built-in modules
• sandbox-mgr-provider / sandbox-provider-api — SPI layer for module loading behavior
• sandbox-module-starter — module authoring support artifact
Core architecture boundaries
1) Target application boundary
This is the host JVM process the sandbox attaches to. The sandbox must avoid contaminating application classes, so it uses explicit classloader isolation and a bootstrap-level spy bridge.
2) Sandbox core boundary
SandboxClassLoader in sandbox-agent and the custom loaders in sandbox-core isolate sandbox implementation classes from the host application. The core includes its own runtime, instrumentation logic, module management, and embedded server.
3) Module boundary
Modules are loaded separately from the core using ModuleJarClassLoader and related loaders. This keeps one module from polluting another and allows dynamic unload/reload.
4) Bootstrap bridge boundary
sandbox-spy is packaged as bootstrap-visible code. Instrumented classes call into Spy, which is reachable from the target application classpath/boot layer. That avoids direct references from transformed application bytecode into sandbox-core classes.
Main subsystems
Agent bootstrap (sandbox-agent)
This is the attach-time entrypoint.
Key responsibilities:
• Receive attach parameters from the command-line tooling
• Bootstrap the sandbox into the target JVM
• Establish the sandbox-specific classloader hierarchy
• Delegate into the core launcher
Important classes:
• AgentLauncher
• SandboxClassLoader
This is the first stage of the system and is responsible for crossing from an external process into the target JVM.
Core runtime (sandbox-core)
This is the central subsystem. It contains most of the implementation.
Major responsibilities:
• Initialize sandbox runtime configuration
• Manage lifecycle of the sandbox inside the target JVM
• Register Java instrumentation transformers
• Load and unload modules
• Start the embedded management server
• Dispatch bytecode events to listeners
• Maintain class metadata and matching logic
Important sub-areas:
Core entry and lifecycle
• CoreLauncher
• JvmSandbox
• CoreConfigure
• CoreModule
These classes assemble the runtime and control startup/shutdown.
Class loading and isolation
• ProviderClassLoader
• ModuleJarClassLoader
• RoutingURLClassLoader
These implement the isolation model:
• sandbox core isolated from the application
• modules isolated from the core and from each other
• provider-chain classes handled separately
Instrumentation and bytecode weaving
• SandboxClassFileTransformer
• Enhancer
• EventEnhancer
• ASM-based weaving under enhance/weaver
This is where target classes are modified at load or retransform time. The transformer inserts event hooks so method execution can be observed and controlled.
The weave layer is built around:
• EventWeaver
• ReWriteAdapter
• CodeLockAdapter
• EventProcessor
• EventListenerHandler
• SingleEventFactory
The design is event-driven: method execution is decomposed into phases such as before, return, and throws.
Class matching and metadata
• CoreLoadedClassDataSource
• matching utilities under util/matcher
• ClassStructure and BehaviorStructure implementations
These support discovering and selecting target classes/methods for enhancement.
Module management
• CoreModuleManager
• DefaultCoreModuleManager
• DefaultModuleManager
• DefaultModuleController
• DefaultModuleEventWatcher
This layer loads module JARs, tracks their lifecycle, and connects them to watched target behaviors.
Embedded server
• CoreServer
• ProxyCoreServer
• JettyCoreServer
• servlet endpoints under server/jetty/servlet
The sandbox embeds a Jetty-based server inside the target JVM. This is used for operational control and module interaction, including HTTP and WebSocket access.
Runtime utilities
The core also contains utility code for:
• reflection
• unsafe access
• logging
• string and collection helpers
• network and environment inspection
• protection/isolation helpers
These utilities support the runtime constraints of running inside another application process.
Bootstrap spy bridge (sandbox-spy)
This module is intentionally tiny and bootstrap-friendly.
Key classes:
• Spy
• SpyHandler
Its role is to act as the communication point from transformed application bytecode back into the sandbox runtime. Instrumented code can invoke this bridge without directly depending on sandbox-core classes, which is essential for classloader isolation and reliable bytecode injection.
Public API for module authors (sandbox-api)
This module defines the extension contract consumed by user modules and built-in modules.
Main categories:
Lifecycle and control contracts
• ModuleLifecycle
• ModuleLifecycleAdapter
• ProcessController
• ProcessControlException
• LoadCompleted
These define how modules start, stop, and influence execution flow.
Event model
• Event and specific events such as:
- BeforeEvent
- ReturnEvent
- ThrowsEvent
- CallBeforeEvent
- CallReturnEvent
- CallThrowsEvent
- LineEvent
- InvokeEvent
This is the main data model flowing from instrumented code into listeners.
Listener and watcher APIs
• EventListener
• ThreadSafeEventListener
• EventListenerFactory
• Sentry
• extended listener types under listener/ext
These define how modules subscribe to runtime events.
Watch/filter abstractions
• EventWatchBuilder
• EventWatcher
• EventWatchCondition
• Filter and related filter types
These are used to describe which classes/methods should be enhanced and monitored.
Module resource interfaces
• ModuleManager
• ModuleController
• ModuleEventWatcher
• LoadedClassDataSource
• EventMonitor
These are the main handles modules use to interact with the core runtime.
HTTP/WebSocket support interfaces
• http.Http
• printer and websocket abstractions
These allow modules to produce command-like output or interact over streaming channels.
Annotations and utility contracts
• Command
• IncludeBootstrap
• IncludeSubClasses
• Stealth
These influence how modules are discovered, isolated, and bound to target classes.
Shared module abstractions (sandbox-common-api)
This is a smaller contract module that sits between core and module implementations.
It contains higher-level shared concepts such as:
• Module
• SandboxModule
• ModuleException
• Information
• ConfigInfo
This appears to define generic module metadata and common module-side types used by both runtime and extension code.
Provider SPI layer (sandbox-provider-api and sandbox-mgr-provider)
This layer defines the loading chain abstraction used by the core when discovering and loading modules and module JARs.
SPI interfaces:
• ModuleLoadingChain
• ModuleJarLoadingChain
Provider implementations in sandbox-mgr-provider include empty/default chain implementations and are registered via Java service loader metadata.
This is an architectural extension point for changing how module artifacts are discovered, filtered, or loaded.
Built-in modules
Management modules (sandbox-mgr-module)
These are operational modules that expose management capabilities inside the sandbox runtime.
Examples:
• InfoModule
• ControlModule
• ModuleMgrModule
They likely map to information display, sandbox control, and module lifecycle management.
Debug modules (sandbox-debug-module)
These are functional examples and operational tools built on top of the API.
Examples:
• DebugTraceModule
• DebugWatchModule
• DebugLogExceptionModule
• DebugLogServletAccessModule
• DebugLifeCycleModule
• DebugRalphModule
These modules illustrate the platform’s purpose: dynamic logging, tracing, exception capture, request access monitoring, and lifecycle debugging.
Main data flow
Attach and bootstrap flow
1. A shell script in bin/ attaches the agent to a running JVM.
2. sandbox-agent loads into the target process.
3. The agent creates or uses SandboxClassLoader to isolate sandbox code.
4. The core is launched through CoreLauncher / JvmSandbox.
5. The core initializes instrumentation, managers, and server components.
Module loading flow
1. Module JARs are discovered using provider chains.
2. Module JARs are loaded by ModuleJarClassLoader.
3. Module lifecycle is invoked through module contracts from sandbox-api and sandbox-common-api.
4. Modules register watches against target behaviors through ModuleEventWatcher.
5. The core records active module state and can unload modules cleanly.
Class enhancement and event flow
1. The target class is matched by the core’s matcher subsystem.
2. SandboxClassFileTransformer rewrites bytecode using ASM-based weavers.
3. Injected bytecode calls into the bootstrap-visible Spy.
4. Spy delegates to sandbox-core handlers.
5. The core emits structured events such as BEFORE, RETURN, THROWS, and call/line events.
6. Registered listeners inside modules consume those events and may:
- observe arguments and return values,
- alter execution flow,
- short-circuit return,
- replace exceptions,
- or throw control exceptions to influence execution.
This event pipeline is the heart of the architecture.
Management/API flow
1. The embedded Jetty server exposes operational endpoints.
2. HTTP/WebSocket handlers in core connect to module and runtime managers.
3. Modules can be controlled interactively through the management layer.
4. Output can be streamed or printed using the API printer abstractions.
Key architectural principles
Non-invasive runtime AOP
The system instruments existing classes in a running JVM rather than requiring code changes or restarts. This is why the classloader boundary and bootstrap spy are so important.
Strict isolation
Isolation is enforced at multiple levels:
• target application vs sandbox core
• core vs modules
• module vs module
• bootstrap bridge vs regular sandbox classes
Dynamic lifecycle
Modules are designed to load and unload at runtime without leaving persistent changes in the host application.
Event-driven control
The entire system is modeled around runtime events instead of direct method interception APIs. That makes it easier to support tracing, logging, flow control, and simulation with the same infrastructure.
Build and packaging structure
The bin/ scripts and Maven multi-module build are part of the operational architecture:
• package the sandbox distribution
• set versions across modules
• install shared APIs locally for development
• attach or detach the sandbox from a target JVM
These scripts do not define runtime behavior, but they are important for deployment and lifecycle operations.
In one diagram, the main layers should be:
• External operator tooling (bin/ scripts)
• Attach agent (sandbox-agent)
• Isolated sandbox core (sandbox-core)
• Bootstrap bridge (sandbox-spy)
• Module API and shared contracts (sandbox-api, sandbox-common-api)
• Module loading SPI/provider layer (sandbox-provider-api, sandbox-mgr-provider)
• Built-in modules (sandbox-mgr-module, sandbox-debug-module)
• Target JVM application being instrumented
The most important arrows are:
• agent attaches into target JVM
• core loads and manages modules
• transformer rewrites target classes
• instrumented code calls spy
• spy hands events to core
• core dispatches events to module listeners
• management server exposes control and introspection channels
Main entry points: JvmSandbox.java Sandbox runtime · manager Module manager · api Sandbox API · enhance Instrumentation
Components 20
Tooling
Scripts and packaging entrypoints used to attach, release, and manage builds.
- Bin scripts · Attach, release, and distribution scripts.
bin
Attach Agent
Entry module that loads the sandbox into a running target JVM.
- Agent launcher · Loads the sandbox into the target JVM.
sandbox-agent/src/main/java/com/alibaba/jvm/sandbox/agent/AgentLauncher.java - Sandbox loader · Isolates sandbox classes during attach.
sandbox-agent/src/main/java/com/alibaba/jvm/sandbox/agent/SandboxClassLoader.java
Sandbox Core
Instrumentation runtime, loaders, managers, server, and utilities inside the target JVM.
- Core launcher · Starts the sandbox core inside the target process.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreLauncher.java - Sandbox runtime · Coordinates lifecycle, configuration, and core services.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/JvmSandbox.java - Core config · Core configuration and startup settings.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreConfigure.java - Class loading · Core and module classloader isolation.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/classloader - Instrumentation · Transforms target classes and injects event hooks.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/enhance - Matchers · Class and behavior matching plus metadata discovery.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/util/matcher - Module manager · Loads, tracks, and unloads sandbox modules.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/manager - Core server · Embedded Jetty-based management server.
sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/server
Bootstrap Bridge
Bootstrap-visible spy used by transformed application bytecode.
- Spy bridge · Bootstrap-visible call-in point from instrumented bytecode.
sandbox-spy/src/main/java/java/com/alibaba/jvm/sandbox/spy/Spy.java - Spy handler · Dispatches bridge calls into sandbox runtime handlers.
sandbox-spy/src/main/java/java/com/alibaba/jvm/sandbox/spy/SpyHandler.java
Public Contracts
Module-facing APIs and shared abstractions.
- Sandbox API · Public event, listener, watcher, and control contracts.
sandbox-api/src/main/java/com/alibaba/jvm/sandbox/api - Common API · Shared module metadata and exception types.
sandbox-common-api/src/main/java/com/alibaba/jvm/sandbox/api
Provider SPI
Extension points for module loading behavior.
- Provider SPI · Interfaces for module loading chains.
sandbox-provider-api/src/main/java/com/alibaba/jvm/sandbox/provider/api - Mgr provider · Default provider-chain implementations and service registration.
sandbox-mgr-provider/src/main/java/com/alibaba/jvm/sandbox/provider/mgr
Built-in Modules
Bundled operational and debugging modules.
- Mgr modules · Built-in management modules for info, control, and module admin.
sandbox-mgr-module/src/main/java/com/alibaba/jvm/sandbox/module/mgr - Debug modules · Tracing, logging, and lifecycle debugging modules.
sandbox-debug-module/src/main/java/com/alibaba/jvm/sandbox/module/debug
Target JVM
The host application being instrumented at runtime.
- Target app · The running Java application being instrumented.
Connections 23
- Bin scripts → Agent launcher: attach · Scripts launch the agent into a running JVM.
- Agent launcher → Sandbox loader: loads via · Agent sets up sandbox-specific classloading.
- Sandbox loader → Core launcher: bootstraps · Agent hands control to the core launcher.
- Core launcher → Sandbox runtime: starts · Launcher creates the runtime inside the target process.
- Sandbox runtime → Core config: reads · Runtime consumes configuration.
- Sandbox runtime → Class loading: isolates · Runtime uses dedicated loaders for core and modules.
- Sandbox runtime → Instrumentation: installs · Runtime registers transformers and weaving.
- Sandbox runtime → Matchers: selects targets · Runtime matches classes and behaviors for enhancement.
- Sandbox runtime → Module manager: manages · Runtime loads and controls modules.
- Sandbox runtime → Core server: exposes · Runtime starts embedded management endpoints.
- Instrumentation → Target app: rewrites · Transforms application classes at load or retransform time.
- Instrumentation → Spy bridge: injects calls · Weaved bytecode calls into the bootstrap bridge.
- Spy bridge → Spy handler: delegates · Bridge forwards events into sandbox logic.
- Spy handler → Sandbox runtime: signals · Runtime receives event callbacks from instrumented code.
- Module manager → Provider SPI: uses SPI · Module loading behavior is extended via provider chains.
- Module manager → Mgr provider: loads providers · Default provider implementations participate in discovery.
- Module manager → Common API: shares types · Module metadata and shared module abstractions are used here.
- Module manager → Sandbox API: implements · Module lifecycle, watchers, and listeners are exposed through the API.
- Core server → Sandbox API: serves · HTTP/WebSocket control surfaces use API abstractions.
- Mgr modules → Sandbox API: implements · Management modules are built on public contracts.
- Debug modules → Sandbox API: implements · Debug modules consume the event and watch APIs.
- Core server → Mgr modules: controls · Operational endpoints drive management modules.
- Module manager → Debug modules: hosts · Core loads debugging modules dynamically.