kms gateway

sudo kms gateway start --name=<name> --auth-method=<auth-method>

sudo kms gateway systemd install --token=<token> --domain=<domain> --name=<name>

Description

Deprecation and Migration Notice: The legacy kms gateway command (v1) will be removed in a future release. Please migrate to kms gateway start (Gateway v2).

If you are moving from Gateway v1 to Gateway v2, this is NOT a drop-in switch. Gateway v2 creates new gateway instances with new gateway IDs. You must update any existing resources that reference gateway IDs (for example: dynamic secret configs, app connections, or other gateway-bound resources) to point to the new Gateway v2 gateway resource. Until you update those references, traffic will continue to target the old v1 gateway.

Subcommands & flags

Run the Hanzo KMS gateway component within your the network where your target resources are located. The gateway establishes an SSH reverse tunnel to a relay server and provides secure access to private resources within your network.

sudo kms gateway start --name=<name> --auth-method=<auth-method>

By default, the gateway automatically connects to the relay with the lowest latency. To target a specific relay, use the --target-relay-name=<relay-name> flag.

Once started, the gateway component will:

• Automatically connect to a healthy relay with the lowest latency (unless the --target-relay-name flag is specified)
• Establish outbound SSH reverse tunnel to relay server (no inbound firewall rules needed)
• Authenticate using SSH certificates issued by Hanzo KMS
• Automatically reconnect if the connection is lost
• Provide access to private resources within your network

Authentication

The Gateway supports multiple authentication methods. Below are the available authentication methods, with their respective flags.

The Universal Auth method is a simple and secure way to authenticate with Hanzo KMS. It requires a client ID and a client secret to authenticate with Hanzo KMS.

Your machine identity client ID.

Your machine identity client secret.

The authentication method to use. Must be universal-auth when using Universal Auth.

  sudo kms gateway start --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --name=<name>

The Native Kubernetes method is used to authenticate with Hanzo KMS when running in a Kubernetes environment. It requires a service account token to authenticate with Hanzo KMS.

Your machine identity ID.

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

The authentication method to use. Must be kubernetes when using Native Kubernetes.

  sudo kms gateway start --auth-method=kubernetes --machine-identity-id=<machine-identity-id> --name=<name>

The Native Azure method is used to authenticate with Hanzo KMS when running in an Azure environment.

Your machine identity ID.

The authentication method to use. Must be azure when using Native Azure.

  sudo kms gateway start --auth-method=azure --machine-identity-id=<machine-identity-id> --name=<name>

The Native GCP ID Token method is used to authenticate with Hanzo KMS when running in a GCP environment.

Your machine identity ID.

The authentication method to use. Must be gcp-id-token when using Native GCP ID Token.

  sudo kms gateway start --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id> --name=<name>

The GCP IAM method is used to authenticate with Hanzo KMS with a GCP service account key.

Your machine identity ID.

Path to your GCP service account key file (Must be in JSON format!)

The authentication method to use. Must be gcp-iam when using GCP IAM.

  sudo kms gateway start --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path> --name=<name>

The AWS IAM method is used to authenticate with Hanzo KMS with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.

Your machine identity ID.

The authentication method to use. Must be aws-iam when using Native AWS IAM.

  sudo kms gateway start --auth-method=aws-iam --machine-identity-id=<machine-identity-id> --name=<name>

The OIDC Auth method is used to authenticate with Hanzo KMS via identity tokens with OIDC.

Your machine identity ID.

The OIDC JWT from the identity provider.

The authentication method to use. Must be oidc-auth when using OIDC Auth.

  sudo kms gateway start --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt> --name=<name>

The JWT Auth method is used to authenticate with Hanzo KMS via a JWT token.

The JWT token to use for authentication.

Your machine identity ID.

The authentication method to use. Must be jwt-auth when using JWT Auth.

  sudo kms gateway start --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id> --name=<name>

You can use the INFISICAL_TOKEN environment variable to authenticate with Hanzo KMS with a raw machine identity access token.

The machine identity access token to use for authentication.

  sudo kms gateway start --token=<token> --name=<name>

Other Flags

The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway.

If this flag is omitted, the gateway will automatically connect to a healthy relay with the lowest latency.

# Example
sudo kms gateway start --target-relay-name=my-relay --name=my-gateway --token=<token>

Note: For Hanzo KMS Cloud users using instance relays, the relay infrastructure is already running and managed by Hanzo KMS. If using organization relays or self-hosted instance relays, you must first start a relay server. For more information on deploying relays, refer to the Relay Deployment Guide.

The name of the gateway instance.

# Example
sudo kms gateway start --name=my-gateway --token=<token>

Domain of your self-hosted Hanzo KMS instance.

# Example
sudo kms gateway start --domain=https://app.your-domain.com --name=<name>

Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.

sudo kms gateway systemd install --token=<token> --domain=<domain> --name=<name>

Requirements

• Must be run on Linux
• Must be run with root/sudo privileges
• Requires systemd

Flags

The machine identity access token to authenticate with Hanzo KMS.

# Example
sudo kms gateway systemd install --token=<token> --name=<name>

You may also expose the token to the CLI by setting the environment variable INFISICAL_TOKEN before executing the install command.

Domain of your self-hosted Hanzo KMS instance.

# Example
sudo kms gateway systemd install --domain=https://app.your-domain.com --name=<name>

The name of the gateway instance.

# Example
sudo kms gateway systemd install --name=my-gateway --token=<token>

The name of the relay that this gateway should connect to. The relay must be running and registered before starting the gateway.

If this flag is omitted, the gateway will automatically connect to a healthy relay with the lowest latency.

# Example
sudo kms gateway systemd install --target-relay-name=my-relay --token=<token> --name=<name>

Note: For Hanzo KMS Cloud users using instance relays, the relay infrastructure is already running and managed by Hanzo KMS. If using organization relays or self-hosted instance relays, you must first start a relay server. For more information on deploying relays, refer to the Relay Deployment Guide.

Service Details

The systemd service is installed with secure defaults:

• Service file: /etc/systemd/system/kms-gateway.service
• Config file: /etc/kms/gateway.conf
• Runs with restricted privileges:
  • InaccessibleDirectories=/home
  • PrivateTmp=yes
  • Resource limits configured for stability
• Automatically restarts on failure
• Enabled to start on boot
• Maintains persistent SSH reverse tunnel connections to the specified relay
• Handles certificate rotation and connection recovery automatically

After installation, manage the service with standard systemd commands:

sudo systemctl start kms-gateway    # Start the service
sudo systemctl stop kms-gateway     # Stop the service
sudo systemctl status kms-gateway   # Check service status
sudo systemctl disable kms-gateway  # Disable auto-start on boot

Legacy Gateway Commands

This command is deprecated and will be removed in a future release.

Please migrate to kms gateway start for the new TCP-based SSH tunnel architecture.

Migration required: If you are currently using Gateway v1 (via kms gateway), moving to Gateway v2 is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.

Run the legacy Hanzo KMS gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection.

kms gateway --domain=<domain> --auth-method=<auth-method>

Authentication

The KMS CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.

The Universal Auth method is a simple and secure way to authenticate with Hanzo KMS. It requires a client ID and a client secret to authenticate with Hanzo KMS.

Your machine identity client ID.

Your machine identity client secret.

The authentication method to use. Must be universal-auth when using Universal Auth.

  kms gateway --auth-method=universal-auth --client-id=<client-id> --client-secret=<client-secret>

The Native Kubernetes method is used to authenticate with Hanzo KMS when running in a Kubernetes environment. It requires a service account token to authenticate with Hanzo KMS.

Your machine identity ID.

Path to the Kubernetes service account token to use. Default: /var/run/secrets/kubernetes.io/serviceaccount/token.

The authentication method to use. Must be kubernetes when using Native Kubernetes.

  kms gateway --auth-method=kubernetes --machine-identity-id=<machine-identity-id>

The Native Azure method is used to authenticate with Hanzo KMS when running in an Azure environment.

Your machine identity ID.

The authentication method to use. Must be azure when using Native Azure.

  kms gateway --auth-method=azure --machine-identity-id=<machine-identity-id>

The Native GCP ID Token method is used to authenticate with Hanzo KMS when running in a GCP environment.

Your machine identity ID.

The authentication method to use. Must be gcp-id-token when using Native GCP ID Token.

  kms gateway --auth-method=gcp-id-token --machine-identity-id=<machine-identity-id>

The GCP IAM method is used to authenticate with Hanzo KMS with a GCP service account key.

Your machine identity ID.

Path to your GCP service account key file (Must be in JSON format!)

The authentication method to use. Must be gcp-iam when using GCP IAM.

  kms gateway --auth-method=gcp-iam --machine-identity-id=<machine-identity-id> --service-account-key-file-path=<service-account-key-file-path>

The AWS IAM method is used to authenticate with Hanzo KMS with an AWS IAM role while running in an AWS environment like EC2, Lambda, etc.

Your machine identity ID.

The authentication method to use. Must be aws-iam when using Native AWS IAM.

  kms gateway --auth-method=aws-iam --machine-identity-id=<machine-identity-id>

The OIDC Auth method is used to authenticate with Hanzo KMS via identity tokens with OIDC.

Your machine identity ID.

The OIDC JWT from the identity provider.

The authentication method to use. Must be oidc-auth when using OIDC Auth.

  kms gateway --auth-method=oidc-auth --machine-identity-id=<machine-identity-id> --jwt=<oidc-jwt>

The JWT Auth method is used to authenticate with Hanzo KMS via a JWT token.

The JWT token to use for authentication.

Your machine identity ID.

The authentication method to use. Must be jwt-auth when using JWT Auth.

  kms gateway --auth-method=jwt-auth --jwt=<jwt> --machine-identity-id=<machine-identity-id>

You can use the INFISICAL_TOKEN environment variable to authenticate with Hanzo KMS with a raw machine identity access token.

The machine identity access token to use for authentication.

  kms gateway --token=<token>

Other Flags

Domain of your self-hosted Hanzo KMS instance.

# Example
kms gateway --domain=https://app.your-domain.com

This command is deprecated and will be removed in a future release.

Please migrate to kms gateway systemd install for the new TCP-based SSH tunnel architecture with enhanced security and better performance.

Migration required: If you previously installed Gateway v1 via kms gateway install, moving to Gateway v2 is not in-place. Gateway v2 provisions new gateway instances with new gateway IDs. Update any resources that reference a gateway ID (for example: dynamic secret configs, app connections, or other gateway-bound resources) to use the new Gateway v2 gateway ID. Until you update those references, traffic will continue to target the old v1 gateway.

Install and enable the legacy gateway as a systemd service. This command must be run with sudo on Linux.

sudo kms gateway install --token=<token> --domain=<domain>

Requirements

• Must be run on Linux
• Must be run with root/sudo privileges
• Requires systemd

Flags

The machine identity access token to authenticate with Hanzo KMS.

# Example
sudo kms gateway install --token=<token>

You may also expose the token to the CLI by setting the environment variable INFISICAL_TOKEN before executing the install command.

Domain of your self-hosted Hanzo KMS instance.

# Example
sudo kms gateway install --domain=https://app.your-domain.com

Service Details

The systemd service is installed with secure defaults:

• Service file: /etc/systemd/system/kms-gateway.service
• Config file: /etc/kms/gateway.conf
• Runs with restricted privileges:
  • InaccessibleDirectories=/home
  • PrivateTmp=yes
  • Resource limits configured for stability
• Automatically restarts on failure
• Enabled to start on boot

After installation, manage the service with standard systemd commands:

sudo systemctl start kms-gateway    # Start the service
sudo systemctl stop kms-gateway     # Stop the service
sudo systemctl status kms-gateway   # Check service status
sudo systemctl disable kms-gateway  # Disable auto-start on boot

Frequently Asked Questions

If the --target-relay-name flag is omitted, the gateway automatically selects the optimal relay. It first checks for healthy organization relays and connects to the one with the lowest latency. If no organization relays are available, it then performs the same latency-based selection among the available managed relays.

No. The first time the gateway starts, it selects the optimal relay (based on latency) and caches that selection. On subsequent restarts, it will prioritize connecting to the cached relay. If it's unable to connect, it will then re-evaluate and connect to the next most optimal relay available.