1.3 Practical: Installing and Running Hyperswitch Locally
Running Hyperswitch locally is the first step toward understanding how the platform behaves as a complete, self-hosted payments system. A local deployment gives developers a production-like environment they can use to explore the Control Center, call APIs, test payment flows, and interact with all the backend services without external dependencies. Hyperswitch uses Helm charts to package and deploy each component Router, Control Center, SDK Resources, Vault, Scheduler, Decision Engine, and its observability stack onto a Kubernetes cluster.
Hyperswitch-Helm is a dedicated repository of Helm charts that packages all the components of Hyperswitch into deployable Kubernetes configurations. Instead of manually writing Kubernetes manifests for each service the Helm charts let you deploy everything with a single command.
Repository: https://github.com/juspay/hyperswitch-helm
Structure of the Helm Charts:
The repository organizes Hyperswitch into multiple Helm charts.
hyperswitch-stack: The umbrella chart that deploys the full Hyperswitch system, including all core services, optional modules, dependencies, and supporting components. It is the recommended entry point for end-to-end deployments.
hyperswitch-app: The core application chart that deploys essential backend services such as the Router/API server, Producer and Consumer components of the Scheduler, the Encryption Service/Key Manager, and other foundational backend subsystems.
hyperswitch-web: Packages the web interface and SDK-facing assets required for merchant and customer experiences, including the Control Center frontend and static assets used by the Web SDK.
hyperswitch-card-vault: Deploys the secure card vault and its associated storage components, ensuring PCI-compliant handling and encryption of payment credentials, tokens, and sensitive data.
hyperswitch-monitoring: Provides the complete observability stack, including Prometheus for metrics, Loki for logs, Tempo for traces, Grafana for visualization, and the OpenTelemetry Collector for standardizing log and trace ingestion.
hyperswitch-control-center: Deploys the backend services for the Hyperswitch Control Center, enabling payment monitoring, connector configuration, user and access management, analytics retrieval, and support for the OMP structure.
Under the hood, these charts may pull in various infrastructure dependencies depending on configuration including databases (such as PostgreSQL), caching layers like Redis, message brokers such as Kafka, and optional observability components.
Now, the below step-by-step guide walks through installing and running Hyperswitch locally using Helm and Kubernetes, giving you a complete, self-contained environment to experiment with and learn from.
Step 1: Install Pre-requisites
Please note that these instructions hold for a macOS and if you are on any other operating system, please install required tools and libraries. Use the below links to install the tools or copy and paste the commands on your terminal mentioned under each of the tool.
Install homebrew. Install kubectl. Install helm. Install orbstack.
homebrew: It is used as the package manager for installing, updating and managing the tools required for local deployment.
helm: It is the package manager used to deploy Hyperswitch’s components onto a Kubernetes cluster.
kubectl: It is the primary command-line tool used to interact with Kubernetes clusters. You will use it to inspect pods, services, logs, and the overall state of your Hyperswitch installation.
orbstack: OrbStack provides a fast, lightweight virtualization environment and includes a built-in Kubernetes cluster suitable for local deployment.
After successful installation verify them by running the following commands.
Sample output to is as below for verification. Versions may change.
Setup OrbStack:
Open the OrbStack app >> Navigate to the Pods section in the left sidebar >> Enable Kubernetes Once Kubernetes is enabled, OrbStack becomes your local cluster runtime.
Step 2: Add the Hyperswitch Helm Repository
Add and update the official Hyperswitch Helm charts. Run the command below.
This downloads metadata for all charts, including:
hyperswitch-stack
hyperswitch-app
hyperswitch-web
hyperswitch-card-vault
hyperswitch-control-center
Hyperswitch-monitoring
Step 3: Install the Hyperswitch Stack
Create a dedicated namespace and install the full stack.Run the command below.
You should see 25 pods running on your orbstack
Router / App Server
Scheduler (Producer, Consumer)
Card Vault
Control Center
Web assets or SDK
Monitoring stack (Grafana, Prometheus, Loki, Tempo, OTel Collector)
Mailhog (email testing)
Step 4: Expose Services to Your Local Machine
To access Hyperswitch components from your browser or development tools, port-forward the services:
Once forwarded, the hyperswitch services can be accessed at below mentioned ports on your local machine.
Control Center → http://localhost:9000
Hyperswitch API → http://localhost:8080
Web SDK Assets → http://localhost:9050/HyperLoader.js
Grafana → http://localhost:3000
Mailhog → http://localhost:8025
Step 5: Verify Your Deployment
Check the API Server: Open http://localhost:8080/health on your browser. This should output “health is good”.
Check the Control Center: Open http://localhost:9000 on your browser. You should see the login screen.
Check Observability: Open http://localhost:3000 on your browser. You should see the grafana login screen. Additionally check that all the 25 pods that are mentioned above run without any issues.
Step 6: Uninstall / Clean Up
If you need to remove the deployment. Run the below command.
This cleans all components and frees cluster resources. With Hyperswitch now running locally, your environment is fully set up to explore real payment flows. In the next section, we will initiate payments through both the SDK and the API and observe how they appear within the Control Center.
Last updated