zGate Documentation
The hands-on reference for the self-hosted zero-trust gateway. Administrators activate a license and deploy the entire stack offline with the interactive TUI installer; developers pull a zero-config CLI straight from your internal server and connect to databases without ever touching real credentials. New to zGate? Start with the Start Here guide.
Core Gateway Concepts
Four ideas underpin everything in this guide: nothing reaches a database without passing through the gateway, identity is cryptographic, every query is inspected inline, and AI backs the whole pipeline. The administrator configures each of these from the Admin Portal.
Zero-Trust Gateway
No direct database port exposure. Every client reaches a database through the zGate proxy, authenticated by an mTLS certificate as identity and short-lived JWTs (5 min) refreshed hourly.
Policy & Masking Interceptors
Every query is inspected inline: Safety rules (Block / Warn / Mask / Allow), JIT approvals, Row / Column / AI masking, and per-role rate limits.
Account Types
Connect through Personal (dedicated), Shared (pooled, on-demand), or Ephemeral (per-session) accounts — assigned per user in the Admin Portal.
AI-Powered Protection
A configurable LLM drives automatic sensitive-column masking, query anomaly detection, and the built-in admin chatbot — all from one provider setting.
Traffic & Interception Pipeline
Server Installation (Enterprise)
The full zGate stack installs offline with a single interactive Linux TUI installer — zero manual container, TLS, or database wiring required.
Infrastructure Prerequisites: Provision an Azure Virtual Machine or equivalent Linux server (Ubuntu 22.04+ or RHEL 9+ recommended). Minimum specs: 2 vCPU, 8GB RAM, 20GB SSD. Ensure ports 80 (HTTP) and 443 (HTTPS) are open. The whole process is for your System Administrator and takes four steps.
License Activation
Run the lightweight helper on the target host to print its unique Machine ID. Send that ID to zGate to contract your license — you'll receive a signed zgate.lic file bound to that machine.
zgate fingerprint
# or
./zgate-installer-linux-amd64 --fingerprintDownload Air-Gapped Assets
Using the secure link provided with your license, download the two air-gapped assets onto the host:
A single .tar.gz bundling every container image the stack needs — no registry access required.
A self-contained interactive installer binary that orchestrates the entire deployment.
Interactive Deployment
Launch the TUI installer and point it at your zgate.lic and the images archive. It validates the license, loads zgate-offline-images.tar.gz, and generates all required secrets and Vault tokens — then presents a “Review & Edit” screen so you can inspect and adjust the configuration and secrets before anything starts.
sudo ./zgate-installer-linux-amd64Launch & First Login
On confirmation, the installer spins the full stack up via Docker Compose. When it finishes, the system is live and it prints the generated Admin Web UI credentials. Head to the Web UI and log in — there are no further server-side steps. Everything else is configured from the .
Admin Portal & Operations
Once the installer finishes the system is live — log into the Web UI with the credentials it generated and configure everything from the browser. No more SQL inserts or config files; each area below is a dedicated page in the Admin Portal.
Databases & Policies
- Add a database: pick the engine (MySQL, MariaDB, PostgreSQL, SQL Server, MongoDB), host & port, admin credentials, and the permissions it may grant (read / write / admin).
- Per-connection TLS: choose Disable, Require, Verify-CA, or Verify-Full, attach a CA certificate, and optionally upload a client cert + key for mutual TLS.
- Build policies from templates: start from a compliance template (HIPAA, GDPR, PCI DSS, ISO 27001, CCPA, SOC 2) or author custom Block / Warn / Mask / Allow rules.
- Masking templates: Row masking (row-level filters), Column masking (hash, encrypt, nullify, truncate, pattern), and AI auto-masking that classifies sensitive columns automatically.
- Roles & assignment: create Roles with per-database permissions and rate limits (queries & bytes per minute/hour/day), attach masking + safety policies, then assign roles to users.
Just-in-Time (JIT) Access
- Attach a “Warn” action to any safety rule so matching queries pause for human review instead of executing immediately.
- The Pending Reviews queue surfaces each held query with its SQL, the requesting user, the target database, and the rule that triggered it.
- Approve or Deny with one click — the developer's query resumes or is rejected in real time.
- Unreviewed requests auto-deny after 5 minutes, so the gateway always fails safe.
DB Account Mapping
- Shared (pooled): a set of real DB credentials shared across users with a max-concurrency cap and a permission level (read-only / read-write / admin).
- Ephemeral: short-lived credentials minted per session and destroyed automatically on disconnect.
- Personal: a persistent, dedicated DB account owned by a single user for a specific database.
- Assign the connection type per user and database to control exactly how each developer reaches the real backend.
Monitoring & Security
- Active Sessions: see every live login with user, IP, user agent, and timestamps — and revoke any session instantly.
- Certificates: review issued mTLS client certificates and revoke a compromised one immediately on detecting unusual behavior.
- Audit, system & access logs: a full, searchable trail of admin actions and user queries for investigation and compliance.
Admin Tiers & M2M
- Three delegated admin tiers beneath the owner: db_admin (databases & accounts), policy_admin (policies & masking), and auditor (read-only logs). The single super owner holds everything.
- Create additional admins, set their tier and account status, and rotate their credentials.
- Service Accounts (M2M): issue a client_id + client_secret (and an optional mTLS certificate) for machine-to-machine workloads, scoped by role and an optional IP allowlist.
- Rotate secrets/certificates, suspend, or permanently revoke a service account at any time.
AI Settings
- Choose the LLM provider and model powering the platform: Ollama (local), OpenAI, Google Gemini, Anthropic Claude, or Azure OpenAI.
- One configuration drives AI Masking (sensitive-column classification), the internal Chatbot assistant, and query anomaly detection.
- API keys are stored encrypted (AES-256-GCM); use Test Connection to validate connectivity before saving.
CLI Installation (Developers)
Developers don't build anything — the CLI is distributed directly from your internal, secure zGate server. One command downloads the right binary and bakes in your server's domain, so it's ready to /login immediately.
Run the one-line installer in your terminal. It pulls the CLI from your zGate server and configures it automatically.
curl -fsSL https://<your-domain.com>/install.sh | bashzgate on your PATH, and writes a config with your internal server domain already injected.Zero-Config Distribution
The binary is served from your own zGate server, and the internal domain is auto-injected into its config at install time. There's nothing to set up — just run zgate and log in.
Cascade Updates
When the core server is upgraded, developers get an in-terminal notification to update. Versioning is strictly enforced: run zgate update to self-update — obsolete clients are blocked from connecting until they do.
Interactive TUI & Commands
Run zgate in your terminal to launch the interactive dashboard. Once in the dashboard, press / to activate the command bar.
Authenticate via SSO (Keycloak browser flow) — always run first
Browse available databases you have access to
Establish local proxy tunnel to a database
View connection status and session information
Manage your active database sessions
Review pending query access requests
Sign out and clear local access tokens
Connecting to Databases (Step-by-Step)
Authenticate
Always start by signing in. Launch the CLI with zgate and run /login to authenticate over SSO (the Keycloak browser flow). Every other command requires an active session.
Discover Resources
Once logged in, type /list to inspect all data stores allocated to your account by system policy.
Establish Connection
Execute /connect my-prod-db. The gateway checks your active sessions and policies, establishes a dynamic local tunnel, and prints client configuration details:
Launch Database Clients
Connect from any IDE (e.g. DBeaver, DataGrip) or CLI shell. Use localhost as target host and the allocated dynamic port (e.g. 59281) as standard port.
Disconnect
Once you terminate your queries or type /status and select disconnect inside the CLI, the tunnel is destroyed, credentials are wiped from keyrings, and shared pooled accounts are recycled securely.