Axon Server Configuration

Axoniq Insights connects to Axon Server to stream events into its analytics engine. This page describes how to configure that connection.

Properties

Parameter Default Description

insights.axonserver.routing-servers

localhost:8124

Comma-separated list of Axon Server routing servers to connect to. Each entry should be in the format host:port. If the port is omitted, it defaults to 8124.

insights.axonserver.token

(empty)

Authentication token for connecting to Axon Server. Required when Axon Server has access control enabled. If empty, no authentication is used.

insights.axonserver.auto-subscribe

false

Whether to automatically subscribe to all contexts available on the Axon Server cluster. If false, contexts must be registered manually through the UI or REST API.

Connecting to a single Axon Server node

The simplest configuration points Insights at a single Axon Server instance:

insights.axonserver.routing-servers=axonserver-host:8124

Port 8124 is the default gRPC port that Axon Server exposes for client connections. If your Axon Server uses a different port, adjust accordingly.

If you omit the port, Insights defaults to 8124:

insights.axonserver.routing-servers=axonserver-host

Connecting to an Axon Server cluster

To connect to an Axon Server cluster, list multiple routing servers separated by commas. Insights uses these as initial contact points and discovers the full cluster topology automatically.

insights.axonserver.routing-servers=axonserver-1:8124,axonserver-2:8124,axonserver-3:8124

Listing multiple nodes provides resilience. Insights can establish a connection even when one or more nodes are temporarily unavailable. Once connected, Insights discovers additional cluster members through the Axon Server cluster protocol.

Authentication

When Axon Server has access control enabled, you must provide a valid authentication token. This is the same token used by other Axon Server clients (for example, Axon Framework applications).

insights.axonserver.token=my-secret-token

You can find or generate this token in the Axon Server Dashboard under Settings > Access Control.

For security, consider passing the token as an environment variable instead of storing it in the properties file: INSIGHTS_AXONSERVER_TOKEN=my-secret-token.

Context management

Axon Server organizes data into contexts. Insights needs to know which contexts to monitor.

Manual context registration (default)

With auto-subscribe set to false (the default), you register contexts individually using the Insights UI or the REST API:

curl -X POST http://localhost:8080/v2/contexts \
  -H "Content-Type: application/json" \
  -d '{"context": "my-context"}'

This gives you fine-grained control over which contexts are monitored and avoids streaming events from contexts you do not need analytics for.

Automatic context discovery

When auto-subscribe is enabled, Insights automatically discovers and subscribes to all contexts on the connected Axon Server cluster:

insights.axonserver.auto-subscribe=true

New contexts created on Axon Server are picked up automatically. This is convenient for development environments or when you want to monitor all contexts without manual intervention.

Docker example

When running both Axon Server and Insights in Docker Compose, use the Docker service name as the hostname:

services:
  axonserver:
    image: docker.axoniq.io/axoniq/axonserver:2025.2.5
    hostname: axonserver-1
    ports:
      - '8024:8024'
      - '8124:8124'

  insights:
    image: docker.axoniq.io/axoniq/axoniq-insights:latest
    environment:
      - insights.axonserver.routing-servers=axonserver-1:8124
    ports:
      - '8080:8080'

In this setup, axonserver-1 resolves to the Axon Server container within the Docker network. There is no need to expose port 8124 on the host unless external clients also need to connect.