Set up the BootUI Java agent

The BootUI Java agent is an optional -javaagent that adds evidence BootUI cannot see from a framework alone: which application methods a request ran (Code Paths), whether the code you just changed executed (Code Inventory), what the application did outside the JVM (Side Effects), and one method's next invocations (method probes). It works on Spring MVC, Spring WebFlux, and Quarkus, in development and tests only. An application started without it behaves exactly as before.

This page takes an application that already runs BootUI (Setup) to a first "did my change run?" answer. The Java Agent reference covers every sensor, state, and property.

1. Get the agent jar

Open BootUI's Java agent panel, or run bootui agent status. Without the agent, both report NOT_ATTACHED and show the jar's expected path in your local Maven repository, with a Download the agent snippet when it is missing:

curl -fL --create-dirs -o ~/.m2/repository/com/julien-dubois/bootui/bootui-agent/<version>/bootui-agent-<version>.jar \
  https://repo1.maven.org/maven2/com/julien-dubois/bootui/bootui-agent/<version>/bootui-agent-<version>.jar

(mvn dependency:get -Dartifact=com.julien-dubois.bootui:bootui-agent:<version> works too.) The agent must be the same version as BootUI: any other version is reported UNAVAILABLE.

2. Add -javaagent to the development JVM

Copy the snippet for your build from the panel or from bootui agent status --json (setup.snippets). For example, for one Spring Boot run:

JAVA_TOOL_OPTIONS='"-javaagent:/path to/bootui-agent.jar"' ./mvnw spring-boot:run

or for Quarkus dev mode:

./mvnw quarkus:dev -Djvm.args="-javaagent:<path to bootui-agent.jar>"

Scope JAVA_TOOL_OPTIONS to one command; never export it in a shell. Never add the agent to a production, native-image, or AOT-cached JVM: Quarkus production mode reports it DISABLED and never claims it, and neither does Spring when bootui.enabled=ON forces BootUI on in a disabled profile such as prod, unless bootui.agent.allow-in-disabled-profiles=true.

3. Check that it is armed

Restart the application, then run bootui agent status or reopen the panel. ARMED means this application claimed the agent; installation and self-tests happen asynchronously, so check each sensor's state before relying on its evidence. Any other agent state comes with its reason; see Status states. The default sensors are executors, inventory, code-paths, processes, network, files, blocking, and resources. Setting bootui.agent.sensors replaces this list: include the defaults you want to keep alongside any opt-in sensors.

4. Answer "did my change run?"

Code Inventory compares this run with the previous one, so it needs a DevTools restart or a Quarkus live reload after the edit:

  1. Change a method and let the application restart or reload.
  2. bootui code inventory lists the changed methods, each EXECUTED, NEVER_EXECUTED, or NOT_TRACKED in this run, with the first request and route when retained. NOT_TRACKED is unknown, not evidence that the method never ran.
  3. Run the test or send the request that should reach a NEVER_EXECUTED method, then read the inventory again.
  4. Still NEVER_EXECUTED? Start a method probe on it (bootui probe start <method>, or Probe in Code Paths on the method in the Code Inventory panel), wait until bootui probe show <id> says active, rerun the same test or request within its 60-second window, and read it again. With the probe active before the rerun and still active after it, or ended only after the rerun finished, invocations at 0 means that path never reaches the method: the wrong route, the wrong bean, or never wired; a probe that never became active, failed, or ended before the rerun finished is inconclusive. A probe is an action: read-only policy refuses it, and it records metadata only, never argument or return values; argument and return shapes are opt-in, in the panel only.

5. Let a coding agent use it

AI agents reach the same evidence through BootUI's MCP server or the CLI. The server's instructions, the verify_after_change prompt, and the agent skill teach them two rules:

  • Call get_agent_status once before relying on an agent-only tool. An observation NOT_APPLICABLE because it requires the BootUI agent was not measured: it is never healthy.
  • Verify, then probe: when an edited method is still not executed after the test that should reach it, ask the user before starting start_method_probe, then read get_method_probe.

See Did my change run? for the tools and their answers.