Setup

BootUI runs on Spring Boot 4 (servlet or WebFlux) and Quarkus, serving the same console and the same JSON contract (at /bootui/api/** by default) from a shared, framework-neutral engine.

The four steps below are the whole servlet install. If you are on WebFlux, follow BootUI on Spring WebFlux instead; on Quarkus, follow BootUI on Quarkus.

1) Prerequisites

• Java 17 or later
• Spring Boot 4.x application
• Maven or Gradle (or their local wrappers)

2) Add the starter dependency

The simplest setup is to drop the starter into your build — nothing else is required. BootUI ships dormant and only wakes up in local development (the dev / local profiles, or when spring-boot-devtools is on the classpath), and it force-disables itself in prod / production.

<dependency>
  <groupId>com.julien-dubois.bootui</groupId>
  <artifactId>bootui-spring-boot-starter</artifactId>
  <version>1.16.0</version>
</dependency>

// Groovy DSL (build.gradle)
runtimeOnly 'com.julien-dubois.bootui:bootui-spring-boot-starter:1.16.0'

// Kotlin DSL (build.gradle.kts)
runtimeOnly("com.julien-dubois.bootui:bootui-spring-boot-starter:1.16.0")

Prefer to keep the starter jar out of your production artifact entirely? Use the dev-only profile setup instead.

3) Run your app in development mode

Start the application with the dev profile active so BootUI turns on:

./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

./gradlew bootRun --args='--spring.profiles.active=dev'

BootUI also activates automatically when spring-boot-devtools is on the classpath. To force it on or off:

bootui.enabled=AUTO
bootui.enabled=ON
bootui.enabled=OFF

prod and production profiles disable BootUI unless bootui.enabled=ON is set. Invalid bootui.enabled values fail closed and keep BootUI disabled.

4) Open BootUI

Nice job! BootUI is now configured 🚀

Visit: http://localhost:8080/bootui

Use a custom path

/bootui is the backward-compatible default. To move the whole console, set:

bootui.path=/dev-console

The shell/assets are then served at /dev-console, and the API, streams, downloads, writes, and MCP endpoint move to /dev-console/api/**. If the API must use a separate mount:

bootui.path=/dev-console
bootui.api-path=/internal/bootui-api

These are application-relative paths. A servlet context path, WebFlux base path, or Quarkus HTTP root path is composed automatically; for example, server.servlet.context-path=/host plus bootui.path=/dev-console produces /host/dev-console. The shell publishes the browser-visible paths to the SPA, so no frontend rebuild is needed.

Paths may use only absolute RFC 3986 unreserved segments. Trailing slashes are removed. Root, empty, encoded, query/fragment, duplicate interior separator, routing-pattern, and . / .. segment values fail startup. Custom UI paths below /bootui/** are reserved and rejected. When a custom path is active, the old /bootui mount returns 404; it is not a compatibility alias. See the property reference for the complete contract.

Next steps

You are done — everything below is optional, and only when you need it.