BootUI

Use BootUI as a local, runtime-grounded source of information for Spring Boot 4 and Quarkus 3 applications. Keep it local-only, preserve its fail-closed defaults, and make the smallest application change that addresses the user's request.

Establish the application context

Before changing anything:

1. Identify the build tool and use its wrapper when present.
2. Identify the framework and web stack:
   • Spring Boot servlet
   • Spring Boot WebFlux
   • Quarkus
3. Confirm Java 17 or later and a supported framework version.
4. Find the runnable module, active development profile, configured HTTP port, and existing BootUI dependency.
5. Run the project's existing focused tests before and after changes when practical.

Do not add both Spring starters. Do not add a Spring starter to Quarkus or the Quarkus extension to Spring.

Install BootUI

Add the dependency only when the user asked for BootUI or approves the change. If a diagnostic request arrives and BootUI is not on the classpath, say so first rather than installing it silently.

Determine the latest stable BootUI version from Maven Central or the BootUI releases; do not guess a version or use a snapshot unless requested. Use the project's existing dependency-management and formatting conventions.

Choose exactly one dependency:

Application	Maven coordinates
Spring Boot servlet	com.julien-dubois.bootui:bootui-spring-boot-starter
Spring Boot WebFlux	com.julien-dubois.bootui:bootui-spring-boot-starter-reactive
Quarkus	com.julien-dubois.bootui:bootui-quarkus

For Spring, prefer a runtime-only Gradle configuration when that matches the build. The Quarkus extension may remain an implementation dependency. Do not add bootui-quarkus-deployment directly.

Activate and run the application in development:

• Spring Maven: ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
• Spring Gradle: ./gradlew bootRun --args='--spring.profiles.active=dev'
• Quarkus Maven: ./mvnw quarkus:dev
• Quarkus Gradle: ./gradlew quarkusDev

BootUI normally opens at http://localhost:<port>/bootui. On Spring, dev or local, DevTools, or bootui.enabled=ON activates it. On Quarkus, dev and test launch modes activate it; production builds remain dark and cannot be forced on.

After installation, verify the application starts, the BootUI banner or URL appears, and GET http://127.0.0.1:<port>/bootui/api/overview returns JSON — bootui overview --url http://127.0.0.1:<port> does the same check when the CLI is installed. Do not treat an unavailable optional panel as an installation failure.

Configure BootUI safely

Only add configuration required by the user's goal. Prefer these safe controls:

• bootui.read-only=true to block all actions.
• bootui.panels.<panel-id>.enabled=false to hide a panel and reject its API.
• bootui.panels.<panel-id>.read-only=true to keep reads while blocking its actions.
• bootui.expose-values=MASKED and bootui.mask-secrets=true as the normal disclosure posture.
• bootui.cli.enabled=false only when the user wants the command-line endpoint off; it is enabled by default.
• bootui.mcp.enabled=ON only when the user wants the MCP server enabled at startup.

Never set bootui.allow-non-localhost=true, bootui.expose-values=FULL, broad trusted proxy ranges, or permissive allowed hosts merely to make a failing request work. Explain the risk and use the narrowest local alternative. For a container, prefer a localhost-bound published port and bootui.trust-container-gateway=AUTO.

Spring supports runtime configuration overrides in .bootui/application-bootui.properties; already-bound configuration may require a restart. The Quarkus Configuration panel is read-only. Do not edit bootui.internal.* properties.

Use the full property reference at https://github.com/jdubois/boot-ui/blob/main/docs/PROPERTIES.md when a setting is not listed here.

Choose how to reach BootUI

BootUI answers the same questions from one tool registry, under the same per-panel enable and read-only policy. The CLI and the MCP server are two spellings of that registry; the browser panels are the human-facing view of the same data. Pick the route already available instead of setting up another:

1. If your tool list already contains BootUI MCP tools, call them directly. Nothing to install or enable. If one answers that the MCP server is disabled, that is the one case where enabling MCP is the right move: tell the user, or set bootui.mcp.enabled=ON, rather than abandoning the request.
2. Otherwise use the bootui command line. Check for it with command -v bootui (Get-Command bootui in PowerShell). Its endpoint is enabled by default, needs no client configuration and no restart, and returns the same masked JSON.
3. If the CLI is not installed, call the endpoint over plain HTTP rather than installing anything. It is ordinary REST, so curl is enough.
4. Point the user at the browser panels when a human should look, or for a screenshot.

Do not enable the MCP server, edit a client configuration, or restart the application merely to run a diagnostic that options 2 and 3 already answer. Set MCP up as a connection when the user asks to connect an agent or MCP client to BootUI.

Use the command-line endpoint

The CLI asks a running application one question and prints the answer. It talks to GET /bootui/api/cli and POST /bootui/api/cli/tools/{name}, which are enabled by default and independent of bootui.mcp.enabled.

Do not install anything to answer a one-off question. The endpoint is plain REST with no JSON-RPC envelope and no token on loopback, so curl reaches the same tools under the same policy:

curl -fsS http://127.0.0.1:8080/bootui/api/cli                       # the catalog
curl -fsS -X POST -H 'Content-Type: application/json' -d '{}' \
  http://127.0.0.1:8080/bootui/api/cli/tools/get_overview
curl -fsS -X POST -H 'Content-Type: application/json' -d '{"limit": 20}' \
  http://127.0.0.1:8080/bootui/api/cli/tools/get_http_exchanges

Always send Content-Type: application/json and a body, {} when the tool takes no argument, exactly as the CLI does. Add -H "Authorization: Bearer $BOOTUI_TOKEN" when bootui.authentication.token is set. The tool names are the MCP tool names; bootui tools and the catalog both list them. On this path the outcome is the HTTP status rather than an exit code: 403 is the panel refusing, the same condition the CLI reports as 2.

Install the bootui command only when the user wants it, or when repeated calls make it worth it — and ask first, because it writes an executable to their machine. It needs a JDK 17 or later. Prefer a source the user can verify: JBang resolves it from Maven Central with jbang app install bootui@jdubois/boot-ui, and the jar can be downloaded from repo1.maven.org and run with java -jar. The installer scripts are a third option; do not pipe one into a shell on the user's behalf without their explicit agreement.

Once it is on the PATH:

bootui tools                                   # what this application actually exposes
bootui --url http://127.0.0.1:8080 overview
bootui hibernate scan --json | jq '.severityCounts'
bootui exceptions show <id> --json
bootui request-profile <id> --json             # one request's SQL, N+1 groups, exceptions, and timing

• --url (or BOOTUI_URL) defaults to http://localhost:8080; pass the application's real port.
• --api-path is only needed when bootui.api-path is customised, --token only when bootui.authentication.token is set, and --timeout raises the 60-second wait for a slow scan.
• Always pass --json when parsing. The human table rendering is not a contract, and terminal auto-detection is unreliable on JDK 22 or later.
• bootui tools prints a human table whose status column reads ready, action, read-only, or panel disabled. With --json it prints the endpoint's own document instead, where each entry in tools carries name, panel, action, arguments, panelEnabled, and panelReadOnly — but no status or command field. Derive availability from those: panelEnabled: false means unavailable, action: true with panelReadOnly: true means the call would be refused. Read this before concluding a stack or panel lacks a capability.
• Exit codes: 0 answered, 1 usage error or unreachable application or a request the tool rejected, 2 BootUI declined because the panel is disabled or read-only. Treat 2 as "not available here", not as a failure to work around by loosening configuration.
• Prefer the BOOTUI_TOKEN environment variable over --token, which exposes the token to shell history and process listings. Never echo a token or copy it into a report.
• Scan payloads differ: pentest scan names its array findings, the rule-based advisors name it results. Every scan shares severityCounts, so prefer that for thresholds, and check the shape with --json | jq keys first.

In CI, capture the exit code (bootui … --json > report.json || status=$?) so a non-zero exit does not abort the step before the application is stopped.

The full command table is at https://github.com/jdubois/boot-ui/blob/main/docs/CLI.md; each command maps to the MCP tool of the same behavior.

Read MySQL operational evidence

The MySQL operational panel supports Oracle MySQL 8.4 LTS and 9.7 LTS, with live coverage on 8.4.6 and 9.7.2; check the running catalog for the application's actual capability. It uses JDBC on Spring MVC, WebFlux, and Quarkus, including named datasources. MariaDB reached through MySQL Connector/J is read but unsupported: its report has serverFlavor MARIADB, an INFO diagnostic, no replication receiver state, and no counter changes. R2DBC-only and reactive-client-only applications are unsupported; do not install another pool just to enable diagnostics.

1. Prefer bootui db mysql report --json / get_mysql_report. This reads the sanitized cache, never MySQL.
2. Only after an explicit request or approval, use bootui db mysql read --json / mysql_read. It is an action that performs bounded external collection despite being read-only at the database. Both tools take no arguments; never supply SQL, a schema, or a server address.
3. Read report status, section reasons, capabilities, observation times, and limitations. The eight areas are vital signs, sessions/blocking, statements, indexes, tables, InnoDB, basic replication, and settings. This is not an advisor: there are no grades or recommendations, and partial/unknown evidence is not a pass.
4. Preserve scope: server-wide counters include other clients, and default-schema-associated sessions/digests do not cover every cross-schema access. Table sizes/rows may be cached estimates; no recorded index activity is not evidence that an index is safe to drop. Failed channel reads do not establish absence of replication.
5. Preserve exact decimal-string counters, byte sizes, and numeric IDs; never round them through JavaScript Number. null means unknown, not zero. Row caps (truncated) differ from permissions, disabled instrumentation, server digest overflow, or timeout failures. Local filters cover retained rows only.

Do not retry busy/partial/failed reads automatically, enable instrumentation, grant PROCESS/other privileges, request raw session/sample SQL or lock keys, or relax exposure/read-only policy. Exposure changes invalidate the cache without SQL, including when relaxed; an explained NOT_READ still needs approval for new collection. The seven bootui.mysql.max-* row limits are static positive integers below 2147483647, requiring restart; raising a CLI timeout does not extend collector or pool budgets. Consult the MySQL guide for exact keys, capability-specific permissions, tested driver/pool combinations, and execution bounds.

Read retained advisor violations

The Architecture, Hibernate, Spring/Quarkus application, REST API, Memory, Security, and Database advisors report true violationCount values but only bounded sampleViolations previews (ten, or twenty for Quarkus application and Security). Never treat the preview as the full affected-target list. Read the cached report first:

scan_id=$(bootui architecture report --json | jq -er '.violationDetails.scanId')
bootui architecture violations ARCH-SPRING-004 --scan-id "$scan_id" --offset 0 --limit 100 --json

Equivalent commands are hibernate violations, spring violations, rest-api violations, memory violations, security violations, and db violations, each with positional rule ID and required --scan-id. The seven MCP tools are get_architecture_rule_violations, get_hibernate_rule_violations, get_spring_rule_violations, get_rest_api_rule_violations, get_memory_rule_violations, get_security_rule_violations, and get_database_advisor_rule_violations. Their arguments are required id and scanId, optional integer offset (default zero, nonnegative) and limit (default 100, positive, capped at min(1000, transport max-results)). Obtain scanId from get_<advisor>_report first.

Architecture, REST API, and Hibernate reports and pages also carry structured locations: sampleLocations aligned with sampleViolations, and locations aligned with violations (a null entry has no location). Each gives className, memberName, kind, sourceFile, line, sourcePath, and precision (LINE, MEMBER, CLASS). Open sourcePath at line to go straight to the code; violationDetails.locationNotes explains a missing path. Never parse a location out of the violation text.

Keep the rule and scan ID fixed, advance the offset by page.returned, and stop when page.hasMore is false. page.total and page.matched count retained entries, not the full violationCount. Inspect rule/report truncated: retention overflow means even a terminal page is incomplete. Report violationDetails contains scanId, total, retained, retentionLimit, and truncated; the default is 10,000 sanitized details per advisor scan (bootui.advisors.max-retained-violations). Raising it cannot recover already discarded details without an explicitly authorized new scan. Detail completeness is not the same as evidence coverage. Truncation can also reflect upstream observations that count affected targets without supplying every identity. Preserve that diagnostic instead of inventing details or assuming a larger retention budget will recover them. Paging does not expand existing observation bounds, such as Memory rules that inspect only their top-five inputs. A PARTIAL Hibernate report names incomplete rules and units in diagnostics (source, unit, level, message); a finding whose units were only partly evaluated carries a coverageNote. INFO diagnostics are advisor limits by design, not missing application configuration. The list is capped at 200 entries; a final entry with source diagnostics states how many were omitted, so a missing unit entry does not prove full coverage. Report these gaps rather than treating the rule as clean.

Detail reads never rerun checks or query a database and remain permitted in read-only mode. Only the latest completed snapshot is kept; dismissal preserves its ID and details. On stale/no-snapshot client error 409, reread the cached report, not the scan tool, and restart pages using its ID. An unknown/non-finding rule is REST/MCP client error 404 (CLI facade 400 by its existing unavailable-tool distinction). On MCP rendered-byte refusal -32003, retry the same scan ID and offset with a smaller limit; never advance after a failure or treat it as an empty page. Stop rather than retry indefinitely when one detail cannot fit. Verify every finding against source and effective configuration before proposing a fix; do not claim complete coverage when truncated.

Use BootUI on a running application

Prefer BootUI's CLI, MCP tools, or browser panels over raw framework internals because BootUI returns bounded, masked DTOs.

1. Confirm the process, port, framework, and BootUI availability, then run bootui tools to see what this application really exposes.
2. Read Overview and Health when the application's identity or overall state matters (bootui overview, bootui health, or get_overview and get_health); go straight to the relevant read when the question is specific.
3. Use Live Activity to correlate recent requests, SQL, exceptions, security events, scheduled work, messaging, and mail.
4. Open the dedicated diagnostic command or panel for full detail.
5. Answer with read commands where you can. Do not run a tool the catalog marks as an action — every … scan, clear, pause, resume, database operational read, and heap analysis — unless the user asked for it or approves after you name it. Prefer an existing … report over a fresh scan, and treat vulnerabilities scan as always requiring approval because it sends package names/versions to OSV.dev and, when enabled, CVE ids to FIRST for EPSS enrichment. Inspect scan status, message, inventory coverage and skipped packages; partial evidence and UNKNOWN severity are not a clean result. Fixed versions are affected-interval candidates, not guaranteed compatible upgrades. EPSS is the highest available per-CVE probability, not combined probability or severity.
6. Record a baseline: finding identifiers and severities, health, failing request, exception, and relevant metrics.

Treat unavailable panels honestly. Their backing library, capability, configuration, or adapter support may be absent. Do not install unrelated infrastructure solely to light up a panel unless the user asks.

Investigate one slow or failing request

1. List recent activity with bootui activity --limit 50 --json (get_live_activity) and pick the REQUEST entry for the request in question. Only an entry with profileable: true has a profile; sqlNPlusOneSuspected and the ERROR or SLOW severities point at the requests worth opening.
2. Fetch its profile with bootui request-profile <id> --json (get_request_profile), passing that entry's id. It returns the same masked profile as the Live Activity drawer: correlated SQL grouped by normalized statement, with N+1 groups and the application call sites that issued them, exceptions, security events, REST client calls, cache accesses, timing, and correlation notes. available: false with an unavailableReason means the request was evicted or cannot be correlated; it is an answer, not an error to retry.
3. For each exception in the profile, read its stack trace and cause chain with bootui exceptions show <exceptionGroupId> --json (get_exception_detail).
4. Check each section's truncated count and the notes before concluding a statement or call did not happen, and treat a TIME_WINDOW tier as approximate.

In the browser, Copy for AI in the Live Activity profile drawer and in an Exceptions detail builds the same evidence as one Markdown document, previewed with what it leaves out before anything is copied. A user may paste one into the conversation instead.

Assess an application and propose an action plan

Use this workflow for a whole-application assessment or "scan everything and tell me what to do" request. A focused runtime question should still use the smallest relevant tools. MCP clients that support prompts can select assess_application; otherwise follow this procedure through the existing MCP tools, CLI, or plain HTTP endpoint. This is an agent workflow, not a new scan tool, server-side assessment job, or code-execution endpoint.

Establish scope and collect evidence

1. Confirm the application URL and API mount, framework, profiles, and instance/start identity when available. Match it to the source repository, revision, and working-tree state. State unknown identity or unavailable source explicitly. Use the user's goal; otherwise state a general application-health goal rather than assuming native-image adoption, a production audit, or an architecture rewrite.
2. Discover the running catalog and panel availability/policy. Account for relevant capabilities without calling every tool; unavailable Spring MVC, WebFlux, or Quarkus features are not failures to work around.
3. Start with existing evidence only: Overview, Health, cached advisor reports, and bounded diagnostic summaries. Assessment does not authorize fresh scans or fixes. Before fresh scans, name the applicable scans and obtain approval for that scope unless already explicitly approved. Request separate approval for memory_scan (may trigger a full GC), pentest_scan (bounded loopback probes), vulnerabilities_scan (outbound OSV.dev queries), and database_advisor_scan (contacts the configured database for metadata). Never run controls, generate traffic, install integrations, or loosen disabled/read-only policy just to improve coverage.
4. Declare a time and tool-call budget before collection. Run approved scans sequentially and stop at the budget; record busy, timed-out, or failed calls rather than retrying indefinitely. Preserve useful evidence from other sources. Respect pagination and mark partial results instead of claiming to have inspected omitted rows.
5. Follow finding, exception, trace, and request identifiers into targeted details and source/configuration inspection. Do not dump every bean, property, log, or trace. Record the collection window and individual report timestamps; a cached report is not a fresh scan, and a collection window is not an atomic JVM snapshot.
6. Mark each relevant capability assessed, unavailable, skipped, failed, or insufficient-evidence, with its reason and stale/partial/paged caveats. Empty telemetry from an idle app is insufficient evidence, not proof that requests or database access are healthy. Request permission for a controlled reproduction if needed.

Advisor numbers are known-findings scores, not app-health grades. Inspect scan.status, retained findings, and report evidence (boolean usable, boolean coverageComplete, immutable bounded sanitized limitations). Usability means at least one applicable check completed or a genuine known-severity finding was observed before filtering/dismissal; informational missing-evidence notices do not establish it. A partial 100 means no active penalties in assessed evidence, not that unseen checks passed. Dismissal changes penalties, not safety. Backend evidence alone establishes eligibility; missing legacy evidence is unscored. For vulnerabilities UNKNOWN cannot establish usability and remains a limitation even after dismissal; genuine INFO/NONE findings can establish usability. Inspect dependency details for the explanation, not a second scoring calculation. Overview averages eligible visible advisor scores and GitHub's eligible security-alert score, showing the contributing count. Missing or unscored reports never supply fake zeros or hundreds. These browser-calculated scores are not returned by get_overview or bootui overview. Existing GET reports do not authorize fresh scans or external queries.