Architecture Overview

Understand PumaGate's gateway and agent architecture for Zero Trust Access.

PumaGate is a Zero-Trust Access platform built around three core components: pumagate.com (cloud platform), the Gateway (connection proxy), and the Agent (on-host runtime). Every connection is authenticated, authorised, and recorded — credentials never leave the agent.

High-Level Architecture

The platform separates the control plane (pumagate.com) from the data plane (Gateway + Agent). Users interact with the pumagate.com dashboard or API; connections flow through the Gateway, which relays traffic to the Agent running on target servers.

👤 User Browser / CLI PUMAGATE.COM Dashboard REST API Auth / RBAC Alerting Integrations GATEWAY SSH / RDP Proxy HTTPS / DB Proxy Session Recording AGENT 1 Metrics + Secrets SSH Server AGENT 2 Metrics + Secrets SSH Server ... more agents Storage Recordings HTTPS Secure Encrypted recordings metrics
pumagate.com (Cloud Platform)

Central management platform providing the dashboard, REST API, authentication, alerting, billing, and integrations. All policy decisions originate here.

Gateway (Connection Proxy)

Stateless proxy that handles SSH, RDP, HTTPS, and database connections. Records every session and communicates securely with agents.

Agent (On-Host Runtime)

Lightweight daemon on each target server. Collects metrics, stores encrypted credentials locally, and provides an SSH server for proxied access.

Zero-Trust Access Flow

Credentials never traverse the network. The Gateway receives only an opaque reference; the Agent resolves the actual credentials locally from its encrypted store. Every session is authenticated, authorised, and fully recorded.

👤 User pumagate.com Auth + RBAC check 1 Login (SSO/MFA) Gateway Creates session 2 session request Agent Resolves credentials 3 connect Target SSH / DB / Web 4 TCP STEP 5 — Bidirectional Data Relay User Gateway Agent Target Encrypted Secure tunnel TCP Recording Store Audit trail persisted 6 🔒 Zero-Trust Principle: Credentials never leave the Agent. The Gateway only receives an opaque reference.
Secret Isolation

Credentials are encrypted at rest on the agent. The Gateway and pumagate.com only handle opaque references, never the actual secrets.

Full Session Recording

All SSH, RDP, and HTTPS sessions are automatically recorded and stored securely for audit and compliance.

Per-Request Auth

Every API call and session request is verified against RBAC policies. OAuth2/SSO with optional MFA is enforced at login. Expired sessions are rejected instantly.

Gateway

The Gateway is a stateless connection proxy that sits between users and Agents. It handles session routing across multiple protocols and records every session for audit and compliance. The Gateway connects securely to pumagate.com for session coordination and to Agents for traffic relay.

SSH Access

Provides browser-based terminal access to any server running the agent. Full session output is recorded for audit and playback.

RDP Access

Provides browser-based remote desktop access to Windows servers. Graphical sessions are recorded for audit and compliance.

Web Application Access

Securely exposes internal web applications with SSO and MFA enforcement at the edge. Supports custom domains.

Database Access

Enables audited MySQL and PostgreSQL access through the agent, without exposing direct database connectivity.

Session Recording

All session types (SSH, RDP, HTTPS, database) are automatically recorded and stored for compliance and forensic review.

Stateless & Scalable

Gateways are stateless and can be scaled horizontally. No session data is stored on the gateway itself.

Agent

The Agent is a lightweight, single-binary daemon that runs on every managed server. It collects system metrics, maintains an encrypted local credential store, and enables proxied access through the Gateway. Credentials never leave the agent — they are resolved locally at connection time.

Lightweight Footprint

Single Go binary with less than 50 MB RAM and under 1% CPU usage. No external dependencies required on the host.

Metric Collection

Collects CPU, memory, disk, network, and service metrics at configurable intervals and reports them to pumagate.com.

Encrypted Credential Store

Credentials are stored locally in encrypted files. Secrets are resolved at connection time and never traverse the network.

Outbound-Only Connectivity

The agent initiates all connections outbound. No inbound ports need to be opened on the host, simplifying firewall configuration.

Network Requirements

The agent requires outbound HTTPS (port 443) connectivity to the PumaGate cloud platform. No inbound ports need to be opened.

DirectionProtocolPortTargetPurpose
Outbound HTTPS 443 pumagate.com API, metrics reporting, agent registration
Outbound HTTPS 443 *.pumagate.com Gateway connectivity, updates
Outbound mTLS 9443 *.pumagate.com Secure tunnel between agent and gateway
No inbound firewall rules are required. The agent establishes all connections outbound to the PumaGate platform.

Alerting Pipeline

The alerting system continuously monitors server health and metric thresholds on pumagate.com, deduplicates events, enforces maintenance windows, and dispatches notifications through multiple channels with escalation policies.

Monitor Checks servers every 2 min Rules Engine Threshold & pattern matching Deduplicator Suppresses duplicate alerts Maintenance Window Suppress if active Notifier Multi-channel dispatch Email Slack Discord Webhook Escalation Policy Loop Re-evaluates unacknowledged alerts periodically Alert Types: Server Down Service Failed Threshold
Rules Engine

Evaluates threshold rules and pattern matching. Supports server-offline and metric-threshold alert types.

Deduplication

Prevents alert storms by suppressing duplicate events within a configurable window. Only fires once per unique condition until resolved.

Escalation Policies

Unacknowledged alerts are periodically re-evaluated and escalated through configured tiers. Supports quiet hours and time-based silencing.

Authentication & RBAC

PumaGate uses session-based authentication with support for OAuth2/SSO providers and MFA. RBAC is enforced at three levels: organisation, team, and group — with permission inheritance flowing downward.

AUTHENTICATION 👤 User Email + Password OAuth2 / SSO MFA (TOTP) Secure Sessions cookie Supported Providers: GitHub Google Azure AD Okta Auth0 RBAC HIERARCHY Org Admin Full access to everything Team A Scoped perms Team B Scoped perms Group: Prod Group: Dev Group: QA srv-01 srv-02 srv-03 srv-04 srv-05 Permission Levels: None View Manage Admin
Multi-Provider SSO

Supports GitHub, Google, Azure AD, Okta, Auth0, and more via OAuth2. Domain-based provisioning auto-assigns users to organisations.

Hierarchical RBAC

Three-level hierarchy: Org Admin (full access), Teams (scoped permissions), Groups (server-level access). Permissions inherit downward through the tree.

API Key + Session Auth

Hybrid authentication supports both session cookies (for the dashboard) and API keys (for programmatic access). Scope-based permissions control API access.

Design Principles

Zero Trust by Design

Every request is verified. Credentials stay on the agent. No implicit trust between components — all communication is authenticated and encrypted.

API-First Architecture

All functionality is exposed through a versioned REST API. The web UI and CLI are consumers of the same API, ensuring consistency across interfaces.

Separation of Concerns

The cloud platform (pumagate.com) is fully separated from the data plane (Gateway). Agents are autonomous and continue operating even if connectivity is lost temporarily.

Multi-Tenant Isolation

All data is scoped to your organisation. RBAC policies enforce strict boundary checks at every level. Cross-tenant access is impossible by design.

Full Audit Trail

Every session is recorded. Every secret access is logged. Change events track infrastructure modifications. Durable, tamper-evident records for compliance.

Horizontally Scalable

Gateways are stateless and can be scaled independently. Agents connect securely, supporting large fleets without coordination overhead.