# alibaba/jvm-sandbox architecture

> Architecture diagram of the GitHub repository alibaba/jvm-sandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alibaba/jvm-sandbox
- Repository: https://github.com/alibaba/jvm-sandbox

## Overview

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: [`sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/JvmSandbox.java`](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/JvmSandbox.java) (Sandbox runtime), [`sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/manager`](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/manager) (Module manager), [`sandbox-api/src/main/java/com/alibaba/jvm/sandbox/api`](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-api/src/main/java/com/alibaba/jvm/sandbox/api) (Sandbox API), [`sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/enhance`](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/enhance) (Instrumentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Tooling"
  bin_scripts["Bin scripts<br/>packaging"]
end

subgraph "Attach Agent"
  agent_launcher["Agent launcher<br/>attach entrypoint<br/>[AgentLauncher.java]"]
  agent_loader["Sandbox loader<br/>agent classloader"]
end

subgraph "Sandbox Core"
  core_launcher["Core launcher<br/>runtime bootstrap<br/>[CoreLauncher.java]"]
  jvm_sandbox["Sandbox runtime<br/>core runtime<br/>[JvmSandbox.java]"]
  core_config["Core config<br/>runtime config<br/>[CoreConfigure.java]"]
  class_loading["Class loading<br/>isolation loaders"]
  instrumentation["Instrumentation<br/>bytecode weaving"]
  matchers["Matchers<br/>class selection"]
  module_manager["Module manager<br/>module lifecycle"]
  core_server["Core server<br/>embedded server"]
end

subgraph "Bootstrap Bridge"
  spy["Spy bridge<br/>bootstrap bridge<br/>[Spy.java]"]
  spy_handler["Spy handler<br/>bridge handler<br/>[SpyHandler.java]"]
end

subgraph "Public Contracts"
  sandbox_api["Sandbox API<br/>module contracts"]
  common_api["Common API<br/>shared module types"]
end

subgraph "Provider SPI"
  provider_api["Provider SPI<br/>loading SPI"]
  mgr_provider["Mgr provider<br/>SPI impl"]
end

subgraph "Built-in Modules"
  mgr_modules["Mgr modules<br/>ops modules"]
  debug_modules["Debug modules"]
end

subgraph "Target JVM"
  target_app(("Target app<br/>host JVM"))
end

bin_scripts -->|"attach"| agent_launcher
agent_launcher -->|"loads via"| agent_loader
agent_loader -->|"bootstraps"| core_launcher
core_launcher -->|"starts"| jvm_sandbox
jvm_sandbox -->|"reads"| core_config
jvm_sandbox -->|"isolates"| class_loading
jvm_sandbox -->|"installs"| instrumentation
jvm_sandbox -->|"selects targets"| matchers
jvm_sandbox -->|"manages"| module_manager
jvm_sandbox -->|"exposes"| core_server
instrumentation -->|"rewrites"| target_app
instrumentation -->|"injects calls"| spy
spy -->|"delegates"| spy_handler
spy_handler -->|"signals"| jvm_sandbox
module_manager -->|"uses SPI"| provider_api
module_manager -->|"loads providers"| mgr_provider
module_manager -->|"shares types"| common_api
module_manager -->|"implements"| sandbox_api
core_server -->|"serves"| sandbox_api
mgr_modules -->|"implements"| sandbox_api
debug_modules -->|"implements"| sandbox_api
core_server -->|"controls"| mgr_modules
module_manager -->|"hosts"| debug_modules

click bin_scripts "https://github.com/alibaba/jvm-sandbox/tree/master/bin"
click agent_launcher "https://github.com/alibaba/jvm-sandbox/blob/master/sandbox-agent/src/main/java/com/alibaba/jvm/sandbox/agent/AgentLauncher.java"
click agent_loader "https://github.com/alibaba/jvm-sandbox/blob/master/sandbox-agent/src/main/java/com/alibaba/jvm/sandbox/agent/SandboxClassLoader.java"
click core_launcher "https://github.com/alibaba/jvm-sandbox/blob/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreLauncher.java"
click jvm_sandbox "https://github.com/alibaba/jvm-sandbox/blob/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/JvmSandbox.java"
click core_config "https://github.com/alibaba/jvm-sandbox/blob/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreConfigure.java"
click class_loading "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/classloader"
click instrumentation "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/enhance"
click matchers "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/util/matcher"
click module_manager "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/manager"
click core_server "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/server"
click spy "https://github.com/alibaba/jvm-sandbox/blob/master/sandbox-spy/src/main/java/java/com/alibaba/jvm/sandbox/spy/Spy.java"
click spy_handler "https://github.com/alibaba/jvm-sandbox/blob/master/sandbox-spy/src/main/java/java/com/alibaba/jvm/sandbox/spy/SpyHandler.java"
click sandbox_api "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-api/src/main/java/com/alibaba/jvm/sandbox/api"
click common_api "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-common-api/src/main/java/com/alibaba/jvm/sandbox/api"
click provider_api "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-provider-api/src/main/java/com/alibaba/jvm/sandbox/provider/api"
click mgr_provider "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-mgr-provider/src/main/java/com/alibaba/jvm/sandbox/provider/mgr"
click mgr_modules "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-mgr-module/src/main/java/com/alibaba/jvm/sandbox/module/mgr"
click debug_modules "https://github.com/alibaba/jvm-sandbox/tree/master/sandbox-debug-module/src/main/java/com/alibaba/jvm/sandbox/module/debug"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class bin_scripts,mgr_modules,debug_modules toneBlue
class agent_launcher,agent_loader,target_app toneAmber
class core_launcher,jvm_sandbox,core_config,class_loading,instrumentation,matchers,module_manager,core_server toneMint
class spy,spy_handler toneRose
class sandbox_api,common_api toneIndigo
class provider_api,mgr_provider toneTeal
```

## Components

### Tooling

Scripts and packaging entrypoints used to attach, release, and manage builds.

- [Bin scripts](https://github.com/alibaba/jvm-sandbox/tree/HEAD/bin): packaging · Attach, release, and distribution scripts. · `bin`

### Attach Agent

Entry module that loads the sandbox into a running target JVM.

- [Agent launcher](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-agent/src/main/java/com/alibaba/jvm/sandbox/agent/AgentLauncher.java): attach entrypoint · Loads the sandbox into the target JVM. · `sandbox-agent/src/main/java/com/alibaba/jvm/sandbox/agent/AgentLauncher.java`
- [Sandbox loader](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-agent/src/main/java/com/alibaba/jvm/sandbox/agent/SandboxClassLoader.java): agent classloader · 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](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreLauncher.java): runtime bootstrap · Starts the sandbox core inside the target process. · `sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreLauncher.java`
- [Sandbox runtime](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/JvmSandbox.java): core runtime · Coordinates lifecycle, configuration, and core services. · `sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/JvmSandbox.java`
- [Core config](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreConfigure.java): runtime config · Core configuration and startup settings. · `sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/CoreConfigure.java`
- [Class loading](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/classloader): isolation loaders · Core and module classloader isolation. · `sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/classloader`
- [Instrumentation](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/enhance): bytecode weaving · Transforms target classes and injects event hooks. · `sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/enhance`
- [Matchers](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/util/matcher): class selection · Class and behavior matching plus metadata discovery. · `sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/util/matcher`
- [Module manager](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/manager): module lifecycle · Loads, tracks, and unloads sandbox modules. · `sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/manager`
- [Core server](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-core/src/main/java/com/alibaba/jvm/sandbox/core/server): embedded 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](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-spy/src/main/java/java/com/alibaba/jvm/sandbox/spy/Spy.java): bootstrap bridge · Bootstrap-visible call-in point from instrumented bytecode. · `sandbox-spy/src/main/java/java/com/alibaba/jvm/sandbox/spy/Spy.java`
- [Spy handler](https://github.com/alibaba/jvm-sandbox/blob/HEAD/sandbox-spy/src/main/java/java/com/alibaba/jvm/sandbox/spy/SpyHandler.java): bridge 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](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-api/src/main/java/com/alibaba/jvm/sandbox/api): module contracts · Public event, listener, watcher, and control contracts. · `sandbox-api/src/main/java/com/alibaba/jvm/sandbox/api`
- [Common API](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-common-api/src/main/java/com/alibaba/jvm/sandbox/api): shared module types · 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](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-provider-api/src/main/java/com/alibaba/jvm/sandbox/provider/api): loading SPI · Interfaces for module loading chains. · `sandbox-provider-api/src/main/java/com/alibaba/jvm/sandbox/provider/api`
- [Mgr provider](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-mgr-provider/src/main/java/com/alibaba/jvm/sandbox/provider/mgr): SPI impl · 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](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-mgr-module/src/main/java/com/alibaba/jvm/sandbox/module/mgr): ops 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](https://github.com/alibaba/jvm-sandbox/tree/HEAD/sandbox-debug-module/src/main/java/com/alibaba/jvm/sandbox/module/debug): 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**: host JVM · The running Java application being instrumented.

## Connections

- 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.
