Skip to content

Getting started

Run Helios as two development processes for the quickest feedback, or launch the full local topology to watch requests rotate across five replicas.

What you need

  • Java 25+
  • Quarkus CLI
  • Docker or Podman
  • An OPENAI_API_KEY

The model defaults to gpt-5.6-sol. Override it with HELIOS_LLM_MODEL when needed.

Option A — dev mode

Start each module from its own directory:

cd mcp-server
quarkus dev

export OPENAI_API_KEY=sk-...
cd agent
quarkus dev

Open localhost:8090. The MCP endpoint is available at localhost:8080/mcp.

The SPA runs in the agent module

In dev mode, http://localhost:8080/ redirects to the MCP server's Dev UI. The console SPA runs at http://localhost:8090/ and needs the second process above. Export OPENAI_API_KEY in that second terminal; a missing key prevents the agent from starting. In the cluster setup below, the SPA uses port 8080 instead.

If dev mode appears stuck, check curl http://localhost:8080/q/health/ready. A response with "status": "UP" means the MCP server is running. Dev mode stays in the foreground; press lowercase h for keyboard shortcuts or w to open the current module's web page. The parent POM disables JLine's terminal probing in dev mode because it can interfere with Quarkus's keyboard input. Restart any dev process started before this setting was added so it takes effect.

One replica, same guarantee

Dev mode starts one MCP server. The server is still stateless; use the cluster option to make request rotation visible.

Option B — five-replica cluster

export OPENAI_API_KEY=sk-...
./start-cluster.sh
open http://localhost:8080

Choose a tool and select Run 5×. The serving instance changes while the business result stays the same.

./stop-cluster.sh

Ask a natural-language question

curl -s localhost:8090/agent/ask \
  -H 'content-type: application/json' \
  -d '{"question":"Where is shipment HLX-10032291 and will it arrive on time?"}'

Try inventory, delivery estimate, carrier SLA, or regional exception questions next.

Package the project

./mvnw clean package
./mvnw clean package -Dnative

Continue with Architecture to understand the request path, or Deployment to move the fleet to OpenShift.