Scaling and High Availability

Enable HA Scaling on the Keeper Gateway

The Keeper Gateway powers Connections, Tunnels, Discovery, and Password Rotation.

Scaling lets you run multiple Gateway instances with the same configuration. Those instances form one Gateway pool. The pool improves capacity and availability for PAM workloads.

A Gateway pool distributes requests across healthy instances in round-robin order.

How Scaling Works

When Gateway scaling is enabled, you can operate multiple Gateway instances using identical configuration. These instances form a Gateway pool that collectively manages PAM workloads.

• Workload distribution — requests are distributed across available Gateway instances.

• Automatic failover — if one instance becomes unavailable, traffic shifts to healthy instances.

• Configurable maximum — you define how many instances can run at once.

• Cross-platform support — instances can run on any supported Gateway platform.

pam gateway list in Commander shows the Gateway Pool as a single entry. Use pam gateway list --verbose to see additional details including OS, machine type, and device name. Individual running instances are not listed separately.

Scaling Down

Reducing the maximum instance count doesn't automatically stop running Gateways — manual intervention is required. If you lower the limit (example: 3 → 2), existing instances continue running until you manually stop them to comply with the new maximum.

Setup

Prerequisites

Before you enable scaling, make sure you have:

• Keeper Gateway version 1.7.6 or higher

• Keeper Commander version 17.2 or higher

• A user who can create, deploy, and manage Keeper Gateways

• An existing Gateway deployment

1. Set Maximum Gateway Instances

After logging into Keeper Commander, retrieve your gateway list:

pam gateway list

Configure scaling for your gateway:

pam gateway set-max-instances -g <GATEWAY_UID_OR_NAME> -m <MAX_INSTANCES>

Where <GATEWAY_UID_OR_NAME> is your Gateway's UID or name, and <MAX_INSTANCES> is your desired concurrent instance limit (minimum: 1).

Example:

pam gateway set-max-instances -g Dmg5bh63p3Yj7ov738BTAw -m 5

2. Run Another Gateway with the Same Configuration

Deploy the same Gateway configuration to additional servers or environments. Each instance joins the same Gateway pool and respects the configured maximum.

Copy the configuration from an existing running Gateway and reuse it on each new host. If you created the original Gateway with the base64 configuration option, reuse that printed GATEWAY_CONFIG value.

For full deployment steps, see the platform guides:

• Gateway with Docker

• Gateway on Linux Native

• Gateway on Windows

Deploying new Instances

Gateway initialization methods differ depending on what system the gateway is deployed on:

• Windows-native and Linux-native gateways are initialized with a One-Time-Token.

• Docker gateways are initialized with a Base64 Configuration file.

Docker Instance

Deploying multiple instances of the same gateway is straightforward with Docker deployments, as the configuration file is the same, therefore you can deploy new instances with the same command:

curl -fsSL https://keepersecurity.com/pam/gatewayctl/install | sudo bash -s -- -c <b64_config>

Linux Instance

Since Linux-native gateways deploy with a One-Time-Token, you cannot add a new instance with the same command. Instead:

1. Install the gateway without a configuration:

curl -fsSL https://keepersecurity.com/pam/install | sudo bash -s

1. Copy the gateway configuration JSON file from your first gateway:

/etc/keeper-gateway/gateway-config.json

1. Restart your gateway

sudo systemctl restart keeper-gateway.service

Windows Instance

Since Linux-native gateways deploy with a One-Time-Token, you cannot add a new instance with the same command. Instead:

1. Install the Windows gateway service without starting it:

1. Copy the gateway configuration JSON file from your first gateway:

C:\ProgramData\KeeperGateway\config\gateway-config.json

1. Start the Keeper Gateway service from your Windows Services list.

Viewing Gateway Instances

After a restart, the gateway should be running as an instance of the gateway pool, and the temporary gateway can be safely discarded. You can verify running instances with Keeper Commander:

pam gateway list
rocky9.gateway                                     pp4pwiBcR5KUV   ONLINE (2 instances)
   |- Instance 1 (connected: 2026-06-11 10:25:30)  10.0.0.57       ONLINE        1.8.1
   |- Instance 2 (connected: 2026-06-11 13:16:19)  10.0.0.47       ONLINE        1.8.1

Converting JSON and Base64 Configuration Files

If you want to run a Linux-native / Windows-native gateway and a Docker gateway together in a pool, the configuration is stored in different formats:

• Linux stores the configuration in JSON

• Docker stores the configuration in Base64 (in the docker-compose.yml file)

To work with both formats, you can encode into / decode from Base64

• Encode a JSON config (Linux / Windows) into Base64 (Docker):

cat /etc/keeper-gateway/gateway-config.json | base64

• Decode a Base64 config (Docker) into JSON (Linux / Windows):

echo 'ewogICAgImF...' | base64 --decode > /etc/keeper-gateway/gateway-config.json

In the above command, > /etc/keeper-gateway/gateway-config.json will write the JSON directly into the gateway config file. Remove it to print the JSON to stdout.