HTTP Server and Dashboard

Introduction

The serve command launches an HTTP server that provides both a browser-based dashboard for visual exploration and a query API for programmatic access. The dashboard lets you explore the code graph, run GQL queries, visualize blast radius, inspect CFGs, and browse communities -- all from your browser. The API endpoints (/api/query, /api/semantic/*) let agents and scripts issue queries without spawning a new process for each one.

Use Cases

• Interactive exploration. Browse functions, classes, and communities in a visual UI.
• Persistent query session. Keep the server running and issue repeated queries over HTTP instead of spawning a new CLI process each time.
• Team sharing. Run the server on a shared host so the whole team can explore the codebase.
• Agent integration. LLM agents can POST queries to /api/query for low-latency, stateful graph access.
• Demo and presentation. Show stakeholders the architecture of a codebase through the dashboard.

Example Project

This guide uses the CoolStore (example/coolstore). rgctl serve can start the full pipeline itself. To only serve existing artifacts:

rgctl -r example/coolstore discover --with-cfg --with-dashboard
rgctl -r example/coolstore serve --no-pipeline --open

The --with-dashboard flag exports the static dashboard bundle to .rgctl/dashboard/.

Step-by-Step

1. Start the Server

Launch the HTTP server with the dashboard:

rgctl -r example/coolstore serve --open

What happens:

• The server starts on http://127.0.0.1:8080.
• The --open flag opens the dashboard in your default browser.
• The dashboard serves from .rgctl/dashboard/ and the query API is available at /api/query.

2. Custom Host and Port

Bind to a different address or port:

rgctl -r example/coolstore serve --host 0.0.0.0 --port 3000

This makes the server accessible on all network interfaces at port 3000, useful for team sharing.

3. Query API Only

If you only need the API (no dashboard UI):

rgctl -r example/coolstore serve --query-only

This starts a lighter server with only the /api/query and /api/semantic/* endpoints.

4. Dashboard Only

If you only need the visual dashboard:

rgctl -r example/coolstore serve --dashboard-only

5. Querying the API with curl

With the server running, issue GQL queries via HTTP:

curl -s http://127.0.0.1:8080/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (f:Function) WHERE f.name = '\''priceShoppingCart'\'' RETURN f"}'

Response:

{
  "count": 1,
  "rows": [
    [
      {
        "binding": "f",
        "file": "example/coolstore/./src/main/java/com/redhat/coolstore/service/ShoppingCartService.java",
        "node": "priceShoppingCart",
        "qualified_name": "com.redhat.coolstore.service.ShoppingCartService.priceShoppingCart",
        "type": "Function"
      }
    ]
  ],
  "schema_version": 1
}

6. Semantic Search via API

Query the semantic index over HTTP:

curl -s http://127.0.0.1:8080/api/semantic/query \
  -H "Content-Type: application/json" \
  -d '{"query": "shopping cart checkout", "limit": 5}'

7. Dashboard tabs

When the dashboard opens in your browser, you will see several tabs:

API Endpoints

See the HTTP API Reference for complete endpoint documentation.

Server Options Reference

Benefits

• Zero setup. One command to launch a full-featured analysis dashboard.
• Dual interface. Visual dashboard for humans, HTTP API for agents and scripts.
• Session persistence. The server keeps the graph in memory, making repeated queries fast.
• Team accessible. Bind to 0.0.0.0 to share the dashboard across a network.
• Low resource. HTTP serve stays up until Ctrl+C.

Related Guides

• Discovering and Indexing a Codebase -- discover --with-dashboard generates the dashboard bundle
• Graph Query Language -- the query language used by the API
• Semantic Search -- semantic queries available via /api/semantic/*
• Blast Radius Analysis -- blast-radius visualization in the dashboard