axelixlabs/axelix repository overview

Axelix is an open-source tool that finds the production problems your Spring Boot apps hide from you, then lets you inspect and debug any running service from a web console or an AI agent

We tend to think of as the the backbone (really!) of the modern Java server-side deployments in the age of AI.

This image is Axelix Master, the central server of the Axelix OSS (community) edition. It bundles the web UI, the REST API, and a built-in MCP server for AI agents, all on a single port.

⁠Quick reference

• Maintained by: Axelix Labs⁠
• Documentation: axelix.io/docs⁠
• Source code: github.com/axelixlabs/axelix⁠
• Where to file issues: GitHub Issues⁠
• Supported architectures: linux/amd64, linux/arm64
• Also published at: ghcr.io/axelixlabs/axelix (same image, same digest)
• License: LGPL-3.0⁠

⁠Supported tags

• latest: the most recent stable release
• <version> (for example 1.3.0): a specific release. Every Axelix component (Master, starters, build plugins) is released under the same version number (lockstep).

All published versions are listed on the Tags⁠ tab and on the GitHub Releases⁠ page. In production, pin a version tag or a digest instead of using latest.

⁠What is Axelix?

An app can pass every test on your laptop and still fail in staging. A property resolves to a value nobody remembers setting. A @ConditionalOnMissingBean wires in the wrong implementation. A Pageable query with JOIN FETCH loads the whole table into the heap. open-in-view is still true in production.

Axelix catches problems like these before they page you. When something is already broken, it shows you the live beans, properties, transactions, and logs of the running JVM, with no redeploy and no SSH.

Live inspectionis available in the web console and as MCP tools for AI agents, governed by the same role-based access model:

• Configuration properties and the exact source of each value
• Beans and @Conditional verdicts, including which auto-configurations matched
• Environment property sources ranked by precedence, with masking of sensitive values
• Logger levels, changed live and audited
• @Transactional method profiles and their likely problems
• Caches, scheduled tasks (toggle, force-run, edit cron expressions), thread and heap dumps, GC and Micrometer metrics
• Instance details: build and git info, JVM, and the Spring / Spring Boot / Spring Cloud versions actually running

⁠How it works

                                         ┌───────────────────────┐
                                         │ Spring Boot Service   │
                         ┌──────────────▶│  + Axelix Starter     │
┌──────────┐         ┌───┴────────┐      └───────────────────────┘
│    UI    │─REST───▶│   Axelix   │      ┌───────────────────────┐
└──────────┘         │   Master   │─────▶│ Spring Boot Service   │
┌──────────┐         │ (UI + MCP) │      │  + Axelix Starter     │
│ AI Agent │─MCP────▶│            │      └───────────────────────┘
└──────────┘         └────────────┘                 ...

Each Spring Boot service you want to manage adds the Axelix Starter dependency and the Axelix build plugin (Gradle or Maven). Master finds services through Kubernetes auto-discovery or through self-registration, where the starter registers with Master on startup. See Configuring the Spring Boot Starter⁠ for the service-side setup.

⁠How to use this image

⁠Start Axelix Master

docker run -d --name axelix -p 2935:2935 axelixlabs/axelix

Then open http://localhost:2935⁠ and sign in with admin / admin.

⁠Run with your own credentials and signing key

docker run -d --name axelix -p 2935:2935 \
  -e AXELIX_MASTER_AUTH_JWT_ALGORITHM=HMAC512 \
  -e AXELIX_MASTER_AUTH_JWT_SIGNINGKEY=replace-with-a-long-random-secret \
  -e AXELIX_MASTER_AUTH_OPTIONS_SUPERADMIN_CREDENTIALS_USERNAME=admin \
  -e AXELIX_MASTER_AUTH_OPTIONS_SUPERADMIN_CREDENTIALS_PASSWORD=change-me \
  axelixlabs/axelix

Master and the managed services authenticate each other with HMAC-signed JWTs. Set the same signing key and algorithm in every managed service (axelix.sbs.auth.jwt.signing-key / axelix.sbs.auth.jwt.algorithm). If they differ, requests fail with 401 and your services never appear in the UI.

⁠Run with Docker Compose and PostgreSQL

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: axelix
      POSTGRES_USER: ${AXELIX_DB_USERNAME:?set AXELIX_DB_USERNAME}
      POSTGRES_PASSWORD: ${AXELIX_DB_PASSWORD:?set AXELIX_DB_PASSWORD}
    volumes:
      - axelix-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 10

  master:
    image: axelixlabs/axelix
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "2935:2935"
    environment:
      AXELIX_MASTER_DATABASE_URL: jdbc:postgresql://postgres:5432/axelix
      AXELIX_MASTER_DATABASE_USERNAME: ${AXELIX_DB_USERNAME}
      AXELIX_MASTER_DATABASE_PASSWORD: ${AXELIX_DB_PASSWORD}
      AXELIX_MASTER_AUTH_JWT_ALGORITHM: HMAC512
      AXELIX_MASTER_AUTH_JWT_SIGNINGKEY: ${AXELIX_JWT_SIGNING_KEY}
      AXELIX_MASTER_AUTH_OPTIONS_SUPERADMIN_CREDENTIALS_USERNAME: ${AXELIX_ADMIN_USERNAME}
      AXELIX_MASTER_AUTH_OPTIONS_SUPERADMIN_CREDENTIALS_PASSWORD: ${AXELIX_ADMIN_PASSWORD}
      AXELIX_MASTER_AUTH_COOKIE_SECURE: "false"   # plain HTTP for local testing; use true behind TLS

volumes:
  axelix-pgdata:

Put the values in an .env file next to the Compose file, keep it out of version control, and run docker compose up -d.

⁠Run on Kubernetes

Use the official Helm chart. It also sets up the RBAC that in-cluster auto-discovery needs:

helm repo add axelix https://axelixlabs.github.io/helm-charts
helm repo update
helm install axelix axelix/axelix --namespace axelix --create-namespace

Chart values are documented on Artifact Hub⁠.

⁠Configuration

Master is a Spring Boot application. Every axelix.master.* property can be set as an environment variable using Spring Boot relaxed binding: uppercase the name, replace . with _, and drop the -. For example, axelix.master.auth.jwt.signing-key becomes AXELIX_MASTER_AUTH_JWT_SIGNINGKEY.

Commonly used settings:

Configuration file. Mount a file and point Master at it:

docker run -d -p 2935:2935 \
  -v /host/config/master.yaml:/etc/axelix/master.yaml:ro \
  -e AXELIX_MASTER_CONFIG_LOCATION=file:/etc/axelix/master.yaml \
  axelixlabs/axelix

JVM options. Use JAVA_TOOL_OPTIONS, for example -e JAVA_TOOL_OPTIONS="-Xmx512m". The JVM prints this variable to the startup log, so never put secrets in it.

Master can also load configuration from Spring Cloud Config Server or HashiCorp Vault, and supports OAuth2/OIDC, local users, Prometheus and OTLP metrics, and structured logging. See the full Configuring Master⁠ reference.

⁠Data persistence

By default Master stores its data in SQLite at /application/axelix.db, inside the container's writable layer. That data is lost when the container is removed. For anything beyond a trial, either:

• use PostgreSQL or MySQL (recommended; also required to run more than one Master replica), or
• mount a volume and point AXELIX_MASTER_DATABASE_URL at a file on it, for example jdbc:sqlite:/data/axelix.db.

Schema migrations run automatically on startup.

⁠Image details

• Based on eclipse-temurin:25-jre-alpine
• Runs as the non-root user axelix, working directory /application
• Ships a JDK Ahead-of-Time (AOT) class-loading cache generated at build time for faster startup & reduced memory footprint
• Writes GC logs, heap dumps on OOM, and JVM crash logs to /tmp, which is declared as a volume
• Exposes port 2935 (can be overriden)

⁠Axelix OSS and Enterprise

This image is the Axelix OSS open core, released under LGPL-3.0. It detects and surfaces problems. Axelix Enterprise (in development) builds on top of it.

⁠Contributing

Contributions are welcome. Read the contribution guide⁠ to get started, and report security issues as described in SECURITY.md⁠.