Topics

#ai-gateway #api-gateway #api-key #api-key-authentication #api-key-management #api-management #api-monitoring #api-proxy #api-security #apim #cloud-native #docker #gateway #hierarchical-structure #kubernetes #lightweight #microservices #open-source #performance #reverse-proxy

Language breakdown

No language data available.

▸ Files click to expand

README

[![][tpi-logo]][tpi-url]

digiRunner:The Unified Control Plane for APIs & AI Services

Bridge your infrastructure to the AI revolution. Securely. An enterprise-grade API Gateway built to govern Microservices and orchestrate Large Language Models (LLMs) with precision. TPI.dev | Documentation | Blog | Community| LinkedIn

Overview

digiRunner is a lightweight, high-performance API Gateway designed for the modern hybrid cloud. As enterprises race to adopt Generative AI, they face a new set of challenges: unpredictable costs, vendor lock-in, and security risks associated with exposing internal data to public models. digiRunner evolves beyond traditional traffic management to become your AI Gateway. It acts as a smart bridge between your applications and AI providers (like OpenAI, Azure, or local Ollama instances), allowing you to decouple your business logic from the rapidly changing AI landscape. With digiRunner, you stop hardcoding API keys and start managing AI as a governed infrastructure asset.

Why digiRunner AI Gateway?

We provide the Guardrails and Governance missing from standard model APIs.

🛡️ Zero Vendor Lock-in (Universal Interface)

Stop rewriting code every time a new model is released.

Provider Abstraction: Define your AI Provider (e.g., OpenAI, Azure) and Model configurations centrally. Your apps call a unified digiRunner endpoint, allowing you to switch backend models instantly without deploying new code.
Secure Key Management: Never expose provider API keys in client-side code again. digiRunner injects credentials securely at the gateway layer.

💰 FinOps & Tokenomics Control

Traditional rate limiting (Requests Per Minute) fails with LLMs, where a single request can consume 10k+ tokens. digiRunner understands Tokenomics.

Granular Cost Control: Enforce strict Input Limits (prevent long context abuse) and Output Limits (prevent runaway generation).
Flexible Policy: Choose between Reject (hard stop) to cap budget, or Use Anyway to allow traffic while flagging overages for audit.

📝 Prompt Engineering as Infrastructure

Treat your Prompts like APIs—versioned, managed, and visible.

Template Registry: Use the built-in AI Prompt Template engine to create, update, and enable/disable prompts globally.
Standardization: Ensure all applications use approved, optimized prompts to reduce hallucinations and ensure brand consistency.

Solving Real API Challenges

| Challenge | digiRunner Solution | |-------------------------------------------|------------------------------------------------------------------------------------------| | Inconsistent access control | Visual RBAC, API keys, OAuth2 & OIDC support | | Disorganized microservice endpoints | Unified API Gateway with intelligent routing | | High learning curve for devs & ops | UI-driven config + AI-powered documentation | | Siloed logs and monitoring gaps | Built-in dashboards and real-time analytics | | Slow APIs dragging down overall system performance. | Intelligent traffic shaping with "Fast Lanes" prioritizes fast APIs, preventing system bottlenecks. | | Limited visibility into performance | Track API performance and catch anomalies before users do | | Lack of scalability and governance | Build API-first apps with policy-based traffic control and enterprise-grade security |

Core API Management Features

Under the hood, digiRunner remains a powerhouse for standard RESTful services:

High Performance: Low-latency routing designed for high-concurrency environments.
K8s & Hybrid Ready: Seamlessly integrates with Kubernetes (K3s/Rancher) for local or cloud deployments.
Full Lifecycle Management: Design, Publish, Secure, and Analyze your APIs from a single dashboard.

Where digiRunner Fits: Real-World Scenarios

digiRunner empowers teams across industries to implement mission-critical API management use cases with ease:

• Financial Services – Enforce security standards and control access to customer transaction APIs across digital banking and fintech ecosystems.

• Retail & E-commerce – Manage catalog, inventory, and checkout APIs with built-in rate limiting, version control, and monitoring during high-traffic seasons.

• Healthcare & Insurance – Govern sensitive API endpoints with fine-grained access policies, audit trails.

• Software & SaaS Providers – Offer a scalable and secure API layer to partners and developers with clear documentation and usage analytics.

• Government & Public Sector – Unify legacy and modern service APIs under a single gateway to simplify external integrations and ensure compliance.

These use cases build on digiRunner’s core strengths in observability, scalability, and governance—giving teams a stable foundation for growth and agility.

Service Structure

Readme<em>Image</em>2025<em>12</em>16

Quick Start

Before installing digiRunner, make sure your machine meets the following minimum system requirements:

>

* CPU >= 2 Core

>

* RAM >= 4 GiB

1. Using Container

choose one of the following options to launch service by container

Option 1: Docker

docker run -it -d -p 31080:18080 tpisoftwareopensource/digirunner-open-source

Option 2: Docker-Compose

Based on the content of deploys/docker-compose/docker-compose.yml

name: digirunner-open-source
services:
    dgr:
        image: tpisoftwareopensource/digirunner-open-source
        ports:
            - "31080:18080"
        environment:
            - TZ=Asia/Taipei

save above configuration to opendgr-compose.yml
run docker-compose -f opendgr-compose.yml up -d at the same directory with opendgr-compose.yml

Option 3: Kubernetes

Based on the content of deploys/kubernetes/digirunner-open-source.yml

apiVersion: v1 kind: Service metadata: name: digirunner-open-source-svc spec: ports: - name: tcp nodePort: 31080 port: 18080 protocol: TCP targetPort: 18080 selector: app: digirunner sessionAffinity: None type: NodePort

apiVersion: apps/v1 kind: Deployment metadata: labels: app: digirunner name: digirunner-open-source-deploy spec: replicas: 1 selector: matchLabels: app: digirunner template: metadata: labels: app: digirunner namespace: digirunner-open-source-ns spec: containers: - env: - name: TZ value: Asia/Taipei image: tpisoftwareopensource/digirunner-open-source imagePullPolicy: Always name: digirunner ports: - containerPort: 18080 name: tcp protocol: TCP workingDir: /opt/digirunner

save above configuration to digirunner-open-source.yml
run kubectl apply -f digirunner-open-source.yml

Option 4: Helm

Contributions:

how-to-package-digirunner-using-helm

- Step-by-step guide on how to package the digirunner open source project using Helm. - Quickly install the example

Connect to service

Open your browser and navigate to: http://localhost:31080/dgrv4/login
Use the default credentials to login:

- username: manager - password: manager123

2. Run digiRunner Instantly on Your Local Machine

If you want to try digiRunner quickly without installation or setup, you can use our pre-packaged version for your operating system.

🧩 Step 1. Download the Package

Choose your OS and download the corresponding file from the release:

macOS (ARM64): [digirunner-opensource-macos-arm64-vX.X.X.X(version).zip]
Windows (AMD64): [digirunner-opensource-windows-amd64-vX.X.X.X(version).zip]

⚙️ Step 2. Extract and Run

Unzip the downloaded package.
Open the extracted folder.
Double-click quickstart.exe to launch digiRunner on your local machine.

You can now start exploring digiRunner immediately — no installation, no configuration required!

🌐 Step 3. Access digiRunner in Your Browser

After launching digiRunner, open your browser and go to:

👉 http://localhost:18080/dgrv4/login

Use the following default credentials to log in:

username: manager
password: manager123

Once logged in, you can start exploring digiRunner’s management console and test its features locally.

⚠️ Note

You may receive a security or firewall warning from macOS or Windows when you run the file for the first time. This is because we haven’t yet registered with Apple or Microsoft developer programs.

Simply allow or bypass the warning (e.g., “Keep Anyway” / “Allow app to run”) to continue.

Once launched, digiRunner will run safely and locally on your machine.

🧹 Step 4. Clean Up

After testing, you can simply delete the entire extracted folder — digiRunner does not modify or install anything on your system.

This Quickstart version is ideal for users who want to:

Test digiRunner locally in just a few minutes
Explore API management features without setup overhead
Safely remove everything after testing

Enjoy your hands-on experience with digiRunner! 💡

3. Run Your Own Build

Pre-requisites

OpenJDK 25

Clone the repository:

git clone https://github.com/TPIsoftwareOSPO/digiRunner-Open-Source.git

Change directory:

cd digiRunner-Open-Source/

Run the service:

./gradlew :dgrv4Gatewayserv:bootRun

Wait for the digiRunner banner to appear.

       _                                           
   | |  |   \                    || |  
  /  |/  | |) | | | | ' \| ' \ /  \ '_| \ \ / / || | 
 | (| | (| |   <| || | | | | | | |  / |     \ V /|   _|
  \,|\, || \\\,|| ||| ||\||      \/    ||  
        |_/                                                  
========== dgRv4 web server info ============
...

Open your browser and navigate to: http://localhost:18080/dgrv4/login
Use the default credentials to login:

- username: manager - password: manager123

Create a Simple API Proxy

Documentation/createasimpleapi_proxy

Documentation

Documentation

Build Your Own JAR

Change to digiRunner directory:

cd digiRunner/

Build the JAR:

./gradlew :dgrv4Gatewayserv:clean :dgrv4Gatewayserv:bootJar

Locate the JAR file: dgrv4Gatewayserv/build/libs/digiRunner-{version}.jar
Run the JAR:

java -jar dgrv4Gatewayserv/build/libs/digiRunner-{version}.jar --digiRunner.token.key-store.path=$PWD/dgrv4Gatewayserv/keys

Run digiRunner in a Local Container Registry

1. Build the Image

Change to digiRunner directory:

cd digiRunner/

Build the Docker image:

docker build -t digirunner .

2. Run the container

docker run -p 18080:18080 digirunner

Open your browser and navigate to: http://localhost:18080/dgrv4/login

SMART on FHIR Proxy

digiRunner implements the HL7 SMART on FHIR STU2.2 standard, acting as both an OAuth 2.0 Authorization Server and a reverse proxy for FHIR API resources. This enables healthcare applications to securely authenticate, authorize, and route FHIR requests across backend servers.

Key Features

SMART App Launch (Standalone & EHR Launch) — Full authorization code flow with PKCE S256 support, scope validation, consent management, and refresh token rotation
FHIR Reverse Proxy — Routes /smart-on-fhir/{proxyName}/* requests to configurable backend FHIR servers with URL rewriting, security checks (SQLi/XSS/XXE), and TPS rate limiting
Client Authentication — Supports public, clientsecretbasic, clientsecretpost, and privatekeyjwt (client assertion per RFC 7523) authentication methods
Diversion & Sticky Routing — Probability-based traffic splitting across multiple backends, with sticky session binding for resource-type affinity
RS256 JWT Tokens — Access tokens are signed using RS256; supports id_token (OIDC), token introspection (RFC 7662), and JWKS endpoint
Management CRUD APIs — Create, update, search, delete, import, and export SMART Client and Proxy configurations via the admin console

Authorization Flow

sequenceDiagram
    participant App as SMART App
    participant DGR as digiRunner Gateway
    participant IdP as Built-in IdP
    participant FHIR as FHIR Server
Note over App,FHIR: Standalone Launch     App->>DGR: GET .well-known/smart-configuration     DGR-->>App: endpoints, capabilities, scopes          App->>DGR: GET /smart/authorize?aud=&clientid=&scope=&redirecturi=&code_challenge=S256     DGR-->>IdP: 302 Redirect to IdP login     IdP-->>App: User authenticates     App->>DGR: GET /smart/callback?code=dgRcode     DGR-->>App: 302 to consent page (or direct auth code if autoApprove)     App->>DGR: POST /smart/approve (approved scopes & patient context)     DGR-->>App: 302 ?code=authCode&state=
App->>DGR: POST /smart/token (granttype=authorizationcode + code_verifier)     DGR-->>App: {accesstoken, idtoken, refresh_token, patient, encounter}
App->>DGR: GET /smart-on-fhir/{proxyName}/Patient/123 (Bearer JWT)     DGR->>+FHIR: Forward request (with security checks)     FHIR-->>-DGR: FHIR Resource     DGR-->>App: Rewritten response (URLs updated)

Discovery Endpoint Response

The .well-known/smart-configuration endpoint returns the SMART on FHIR capabilities. It is served at the proxy URL path:

GET http://localhost:18080/smart-on-fhir/{proxyName}/.well-known/smart-configuration

{
  "token_endpoint": "http://localhost:18080/dgrv4/ssotoken/smart/token",
  "granttypessupported": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "capabilities": [
    "launch-standalone",
    "launch-ehr",
    "client-public",
    "client-confidential-symmetric",
    "client-confidential-asymmetric",
    "context-standalone-patient",
    "context-ehr-patient",
    "context-ehr-encounter",
    "permission-patient",
    "permission-user",
    "permission-v2",
    "permission-offline",
    "sso-openid-connect"
  ],
  "codechallengemethods_supported": [
    "S256"
  ],
  "issuer": "http://localhost:18080",
  "jwks_uri": "http://localhost:18080/dgrv4/ssotoken/smart/jwks",
  "authorization_endpoint": "http://localhost:18080/dgrv4/ssotoken/smart/authorize",
  "scopes_supported": [
    "openid",
    "fhirUser",
    "profile",
    "launch",
    "launch/patient",
    "launch/encounter",
    "patient/*.cruds",
    "user/*.cruds",
    "system/*.cruds",
    "offline_access"
  ],
  "responsetypessupported": [
    "code"
  ],
  "introspection_endpoint": "http://localhost:18080/dgrv4/ssotoken/smart/introspect",
  "revocation_endpoint": "http://localhost:18080/dgrv4/ssotoken/smart/revoke",
  "tokenendpointauthmethodssupported": [
    "clientsecretbasic",
    "clientsecretpost",
    "privatekeyjwt"
  ]
}

Quick Start

Step 1: Create a SMART Client

In the admin UI, navigate to SMART Client Setting and register a client:

Client ID, Type (public/confidential), Allowed Scopes (e.g., patient/*.read, openid, profile), Redirect URIs, Launch Mode (standalone/ehr/both)

Step 2: Create a FHIR Proxy

In SMART on FHIR Proxy, create a proxy configuration:

Proxy Name (used in the URL path), Backend FHIR Server URLs, Diversion weights, Security settings (enable SQLi/XSS/XXE checks), TPS limit

Step 3: Configure Sticky Routing (optional)

Bind specific FHIR resource types to diversion targets for session affinity.

Step 4: Obtain an Access Token

Use the SMART App Launch flow to obtain a JWT access token, or use client_credentials grant with client assertion for Backend Services.

Step 5: Call FHIR Resources

curl -H "Authorization: Bearer <access_token>" \
  http://localhost:18080/smart-on-fhir/{proxyName}/Patient/123

[tpi-url]: https://tpi.dev/ [tpi-logo]: /digiRunner.png

🏅 Community Badges

We recognize outstanding contributors through our badge system.

⚠️ Important Note: > These are OpenTPI/digiRunner community-specific honors designed to celebrate your contributions. Please note that these are not official GitHub Profile Achievements.

Badges are proudly displayed in our Community_Badges.md. They will not automatically appear on your personal GitHub Profile, though you are highly encouraged to add the badge snippets to your own profile!

First Step Badge Project Builder Badge