0
# Byte Buddy Agent
1

2
The Byte Buddy agent provides convenient APIs for attaching Java agents to local or remote virtual machines. It offers runtime installation capabilities for Java agents without requiring command-line specification, supports multiple JVM implementations including HotSpot and OpenJ9, and provides cross-platform attachment mechanisms through JNA integration.
3

4
## Package Information
5

6
- **Package Name**: byte-buddy-agent
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  - Maven: `<dependency><groupId>net.bytebuddy</groupId><artifactId>byte-buddy-agent</artifactId><version>1.17.7</version></dependency>`
11
  - Gradle: `implementation 'net.bytebuddy:byte-buddy-agent:1.17.7'`
12

13
## Core Imports
14

15
```java
16
import net.bytebuddy.agent.ByteBuddyAgent;
17
import java.lang.instrument.Instrumentation;
18
```
19

20
For advanced usage:
21

22
```java
23
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
24
import net.bytebuddy.agent.ByteBuddyAgent.ProcessProvider;
25
import net.bytebuddy.agent.VirtualMachine;
26
import net.bytebuddy.agent.Installer;
27
```
28

29
## Basic Usage
30

31
```java
32
import net.bytebuddy.agent.ByteBuddyAgent;
33
import java.lang.instrument.Instrumentation;
34

35
// Install agent on current JVM and get instrumentation
36
Instrumentation instrumentation = ByteBuddyAgent.install();
37

38
// Use instrumentation for runtime class modification
39
Class<?>[] loadedClasses = instrumentation.getAllLoadedClasses();
40
boolean canRedefine = instrumentation.isRedefineClassesSupported();
41

42
// Attach agent JAR to remote process
43
File agentJar = new File("my-agent.jar");
44
String processId = "1234";
45
ByteBuddyAgent.attach(agentJar, processId);
46

47
// Attach agent with arguments
48
ByteBuddyAgent.attach(agentJar, processId, "agent-arguments");
49
```
50

51
## Architecture
52

53
Byte Buddy Agent is built around several key components:
54

55
- **ByteBuddyAgent**: Main API facade providing high-level agent installation and attachment methods
56
- **Installer**: Agent entry-point class implementing premain/agentmain hooks required by Java agent specification
57
- **Attachment System**: Pluggable providers supporting different JVM attachment mechanisms (tools.jar, modules, JNA)
58
- **Virtual Machine Abstraction**: Cross-platform VM interaction layer supporting HotSpot, OpenJ9, and platform-specific communication protocols
59
- **Process Management**: Process discovery and management utilities for cross-VM operations
60

61
This design enables runtime Java agent deployment across different JVM implementations and operating systems while providing a unified API for agent installation and VM attachment.
62

63
## Capabilities
64

65
### Agent Installation
66

67
Core functionality for installing Java agents on the current JVM at runtime. Provides access to the Instrumentation API for bytecode manipulation and class redefinition.
68

69
```java { .api }
70
// Install agent on current JVM
71
public static Instrumentation install();
72
public static Instrumentation install(AttachmentProvider attachmentProvider);
73
public static Instrumentation install(ProcessProvider processProvider);
74
public static Instrumentation install(AttachmentProvider attachmentProvider, ProcessProvider processProvider);
75

76
// Get existing instrumentation instance
77
public static Instrumentation getInstrumentation();
78
```
79

80
[Agent Installation](./agent-installation.md)
81

82
### Agent Attachment
83

84
Remote attachment capabilities for deploying Java agents to other JVM processes. Supports both JAR-based agents and native agent libraries with flexible process targeting.
85

86
```java { .api }
87
// Attach JAR agents to remote processes
88
public static void attach(File agentJar, String processId);
89
public static void attach(File agentJar, String processId, String argument);
90
public static void attach(File agentJar, ProcessProvider processProvider);
91
public static void attach(File agentJar, ProcessProvider processProvider, String argument);
92

93
// Attach native agents
94
public static void attachNative(File agentLibrary, String processId);
95
public static void attachNative(File agentLibrary, String processId, String argument);
96
```
97

98
[Agent Attachment](./agent-attachment.md)
99

100
### Virtual Machine Operations  
101

102
Low-level virtual machine interaction interface providing direct access to VM operations including property access, agent loading, and management agent control. Used internally by attachment mechanisms and available for advanced use cases.
103

104
```java { .api }
105
// VM property access
106
Properties getSystemProperties() throws IOException;
107
Properties getAgentProperties() throws IOException;
108

109
// Agent loading operations  
110
void loadAgent(String jarFile) throws IOException;
111
void loadAgent(String jarFile, String argument) throws IOException;
112
void loadAgentPath(String path) throws IOException;
113
void loadAgentLibrary(String library) throws IOException;
114

115
// Management operations
116
void startManagementAgent(Properties properties) throws IOException;
117
String startLocalManagementAgent() throws IOException;
118
void detach() throws IOException;
119
```
120

121
[Virtual Machine Operations](./vm-operations.md)
122

123
### Cross-Platform Support
124

125
Platform-specific implementations and attachment providers enabling cross-JVM and cross-OS compatibility. Includes support for different attachment mechanisms, process management, and native integrations.
126

127
```java { .api }
128
// Attachment provider interface
129
interface AttachmentProvider {
130
    Accessor attempt();
131
}
132

133
// Process provider interface  
134
interface ProcessProvider {
135
    String resolve();
136
}
137

138
// Pre-configured providers
139
AttachmentProvider DEFAULT = new Compound(/* multiple providers */);
140
ProcessProvider.ForCurrentVm INSTANCE = /* current JVM provider */;
141
```
142

143
[Cross-Platform Support](./cross-platform.md)