0
# Agent Installation
1

2
Core functionality for installing Java agents on the current JVM at runtime, providing access to the Instrumentation API for bytecode manipulation and class redefinition without requiring command-line agent specification.
3

4
## Capabilities
5

6
### Runtime Agent Installation
7

8
Install a Byte Buddy agent on the currently running JVM to enable runtime bytecode instrumentation. The agent provides access to the Java Instrumentation API for class redefinition and transformation.
9

10
```java { .api }
11
/**
12
 * Installs an agent on the currently running Java virtual machine using the default attachment provider.
13
 * @return An instrumentation instance representing the currently running JVM
14
 * @throws IllegalStateException If the agent cannot be installed
15
 */
16
public static Instrumentation install();
17

18
/**
19
 * Installs an agent using the supplied attachment provider.
20
 * @param attachmentProvider The attachment provider to use for the installation
21
 * @return An instrumentation instance representing the currently running JVM
22
 * @throws IllegalStateException If the agent cannot be installed
23
 */
24
public static Instrumentation install(AttachmentProvider attachmentProvider);
25

26
/**
27
 * Installs an agent on the Java virtual machine resolved by the process provider.
28
 * @param processProvider The provider for the current JVM's process id
29
 * @return An instrumentation instance representing the currently running JVM
30
 * @throws IllegalStateException If the agent cannot be installed
31
 */
32
public static Instrumentation install(ProcessProvider processProvider);
33

34
/**
35
 * Installs an agent using the supplied attachment provider and process provider.
36
 * @param attachmentProvider The attachment provider to use for the installation
37
 * @param processProvider The provider for the current JVM's process id
38
 * @return An instrumentation instance representing the currently running JVM
39
 * @throws IllegalStateException If the agent cannot be installed
40
 */
41
public static synchronized Instrumentation install(AttachmentProvider attachmentProvider, ProcessProvider processProvider);
42
```
43

44
### Instrumentation Access
45

46
Retrieve the Instrumentation instance from an already installed Byte Buddy agent. This method provides access to the JVM's instrumentation capabilities without reinstalling the agent.
47

48
```java { .api }
49
/**
50
 * Looks up the Instrumentation instance of an installed Byte Buddy agent.
51
 * @return The Instrumentation instance provided by an installed Byte Buddy agent
52
 * @throws IllegalStateException If the Byte Buddy agent is not properly installed
53
 */
54
public static Instrumentation getInstrumentation();
55
```
56

57
### Agent Hook Methods (Installer Class)
58

59
These methods are called by the JVM when the agent is loaded. They are part of the Java agent specification and should not be called directly by user code. These methods are located in the `Installer` class, not `ByteBuddyAgent`.
60

61
```java { .api }
62
/**
63
 * Allows the installation of this agent via a command line argument.
64
 * @param arguments The unused agent arguments
65
 * @param instrumentation The instrumentation instance
66
 */
67
public static void premain(String arguments, Instrumentation instrumentation);
68

69
/**
70
 * Allows the installation of this agent via the attach API.
71
 * @param arguments The unused agent arguments  
72
 * @param instrumentation The instrumentation instance
73
 */
74
public static void agentmain(String arguments, Instrumentation instrumentation);
75
```
76

77
## Usage Examples
78

79
### Basic Installation
80

81
```java
82
import net.bytebuddy.agent.ByteBuddyAgent;
83
import java.lang.instrument.Instrumentation;
84

85
// Install agent and get instrumentation
86
Instrumentation instrumentation = ByteBuddyAgent.install();
87

88
// Use instrumentation capabilities
89
Class<?>[] loadedClasses = instrumentation.getAllLoadedClasses();
90
boolean canRedefine = instrumentation.isRedefineClassesSupported();
91
boolean canRetransform = instrumentation.isRetransformClassesSupported();
92

93
System.out.println("Loaded classes: " + loadedClasses.length);
94
System.out.println("Can redefine: " + canRedefine);
95
System.out.println("Can retransform: " + canRetransform);
96
```
97

98
### Custom Attachment Provider
99

100
```java
101
import net.bytebuddy.agent.ByteBuddyAgent;
102
import net.bytebuddy.agent.ByteBuddyAgent.AttachmentProvider;
103

104
// Use a specific attachment provider
105
AttachmentProvider provider = AttachmentProvider.ForModularizedVm.INSTANCE;
106
Instrumentation instrumentation = ByteBuddyAgent.install(provider);
107

108
// Or use compound provider with custom strategy
109
AttachmentProvider customProvider = new AttachmentProvider.Compound(
110
    AttachmentProvider.ForModularizedVm.INSTANCE,
111
    AttachmentProvider.ForJ9Vm.INSTANCE
112
);
113
instrumentation = ByteBuddyAgent.install(customProvider);
114
```
115

116
### Safe Installation Check
117

118
```java
119
import net.bytebuddy.agent.ByteBuddyAgent;
120
import java.lang.instrument.Instrumentation;
121

122
try {
123
    // Try to get existing instrumentation first
124
    Instrumentation instrumentation = ByteBuddyAgent.getInstrumentation();
125
    System.out.println("Agent already installed");
126
} catch (IllegalStateException e) {
127
    // Install agent if not already present
128
    System.out.println("Installing agent...");
129
    Instrumentation instrumentation = ByteBuddyAgent.install();
130
    System.out.println("Agent installed successfully");
131
}
132
```
133

134
## JVM Compatibility
135

136
The runtime installation of a Java agent is supported for:
137

138
- **Java 9+**: Uses the `jdk.attach` module when available (typically JDK distributions)
139
- **Java 8 and earlier**: Requires `tools.jar` from JDK installations (HotSpot, OpenJDK, IBM J9)
140
- **Linux systems**: Optional JNA-based Unix socket emulation when JDK attachment is unavailable
141
- **All platforms**: Automatic fallback through multiple attachment provider strategies
142

143
## Important Notes
144

145
- **Computation-heavy operation**: Installation is expensive and cached after first success
146
- **Synchronization required**: Installation method is synchronized to prevent race conditions  
147
- **Security permissions**: Requires `net.bytebuddy.agent.getInstrumentation` runtime permission when security manager is active
148
- **JDK requirement**: Most attachment mechanisms require JDK (not JRE) distributions
149
- **Same-user limitation**: Can only attach to processes running under the same operating system user