digiRunner-Open-Source

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

Table of contents

• Overview
• Quick Start
  • Using Container
    • Option 1: Docker
    • Option 2: Docker-Compose
    • Option 3: Kubernetes
    • Option 4: Helm
  • Run digiRunner Instantly on Your Local Machine
  • Run Your Own Build
• Create a Simple Api Proxy
• Documentation
• Build Your Own JAR
• Run digiRunner in a Local Container Registry

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.

1. 🛡️ 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.

2. 💰 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.

3. 📝 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

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

1. Unzip the downloaded package.
2. Open the extracted folder.
3. 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

---

1. Clone the repository:

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

2. Change directory:

   cd digiRunner-Open-Source/
   

3. Run the service:

   ./gradlew :dgrv4_Gateway_serv:bootRun
   

4. Wait for the digiRunner banner to appear.

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

5. Open your browser and navigate to: http://localhost:18080/dgrv4/login
6. Use the default credentials to login:
   • username: manager
   • password: manager123

Create a Simple API Proxy

• Documentation/create_a_simple_api_proxy

Documentation

• Documentation

Build Your Own JAR

1. Change to digiRunner directory:

   cd digiRunner/
   

2. Build the JAR:

   ./gradlew :dgrv4_Gateway_serv:clean :dgrv4_Gateway_serv:bootJar
   

3. Locate the JAR file: dgrv4_Gateway_serv/build/libs/digiRunner-{version}.jar

4. Run the JAR:

   java -jar dgrv4_Gateway_serv/build/libs/digiRunner-{version}.jar --digiRunner.token.key-store.path=$PWD/dgrv4_Gateway_serv/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, client_secret_basic, client_secret_post, and private_key_jwt (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=&client_id=&scope=&redirect_uri=&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 (grant_type=authorization_code + code_verifier)
    DGR-->>App: {access_token, id_token, 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",
  "grant_types_supported": [
    "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"
  ],
  "code_challenge_methods_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"
  ],
  "response_types_supported": [
    "code"
  ],
  "introspection_endpoint": "http://localhost:18080/dgrv4/ssotoken/smart/introspect",
  "revocation_endpoint": "http://localhost:18080/dgrv4/ssotoken/smart/revoke",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt"
  ]
}

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

🏅 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

• 📘 Badge Criteria
• 👑 Badge Recipients