diff --git a/docs/cli/commands/gateway.mdx b/docs/cli/commands/gateway.mdx
index a12493c58..0168c7a42 100644
--- a/docs/cli/commands/gateway.mdx
+++ b/docs/cli/commands/gateway.mdx
@@ -3,6 +3,22 @@ title: "infisical gateway"
description: "Run the Infisical gateway or manage its systemd service"
---
+
+**New Gateway Architecture Available**
+
+A completely redesigned gateway system is now available under the `infisical network` command with a fundamentally different architecture:
+
+- **TCP-based SSH tunnels** instead of UDP/TURN protocol
+- **Eliminates firewall complexity** - no UDP configuration needed
+- **Enhanced security** with certificate-based authentication
+- **Flexible deployment options** - instance-wide or organization-specific proxies
+
+**Learn more:** See [`infisical network`](/cli/commands/network) for the new gateway architecture.
+
+**Migration:** The current `infisical gateway` command will continue to work but **will be deprecated in a future release**. Migration to `infisical network gateway` requires **complete reconfiguration** - you cannot simply switch commands as this is an entirely different gateway infrastructure. We strongly recommend planning migration to `infisical network gateway` for all deployments.
+
+
+
```bash
@@ -25,13 +41,13 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
Run the Infisical gateway in the foreground. The gateway will connect to the relay service and maintain a persistent connection.
- ```bash
- infisical gateway --domain= --auth-method=
- ```
+```bash
+infisical gateway --domain= --auth-method=
+```
- ### Authentication
+### Authentication
- The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.
+The Infisical CLI supports multiple authentication methods. Below are the available authentication methods, with their respective flags.
@@ -121,7 +137,6 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
infisical gateway --auth-method=gcp-id-token --machine-identity-id=
```
-
The GCP IAM method is used to authenticate with Infisical with a GCP service account key.
@@ -163,7 +178,6 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
infisical gateway --auth-method=aws-iam --machine-identity-id=
```
-
The OIDC Auth method is used to authenticate with Infisical via identity tokens with OIDC.
@@ -185,6 +199,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
```bash
infisical gateway --auth-method=oidc-auth --machine-identity-id= --jwt=
```
+
@@ -208,6 +223,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
```bash
infisical gateway --auth-method=jwt-auth --jwt= --machine-identity-id=
```
+
You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token.
@@ -227,7 +243,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
- ### Other Flags
+### Other Flags
Domain of your self-hosted Infisical instance.
@@ -236,22 +252,24 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
# Example
infisical gateway --domain=https://app.your-domain.com
```
+
Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.
- ```bash
- sudo infisical gateway install --token= --domain=
- ```
+```bash
+sudo infisical gateway install --token= --domain=
+```
- ### Requirements
- - Must be run on Linux
- - Must be run with root/sudo privileges
- - Requires systemd
+### Requirements
- ### Flags
+- Must be run on Linux
+- Must be run with root/sudo privileges
+- Requires systemd
+
+### Flags
The machine identity access token to authenticate with Infisical.
@@ -262,6 +280,7 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
```
You may also expose the token to the CLI by setting the environment variable `INFISICAL_TOKEN` before executing the install command.
+
@@ -271,24 +290,29 @@ Run the Infisical gateway in the foreground or manage its systemd service instal
# Example
sudo infisical gateway install --domain=https://app.your-domain.com
```
+
- ### Service Details
- The systemd service is installed with secure defaults:
- - Service file: `/etc/systemd/system/infisical-gateway.service`
- - Config file: `/etc/infisical/gateway.conf`
- - Runs with restricted privileges:
- - InaccessibleDirectories=/home
- - PrivateTmp=yes
- - Resource limits configured for stability
- - Automatically restarts on failure
- - Enabled to start on boot
+### Service Details
+
+The systemd service is installed with secure defaults:
+
+- Service file: `/etc/systemd/system/infisical-gateway.service`
+- Config file: `/etc/infisical/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:
+
+```bash
+sudo systemctl start infisical-gateway # Start the service
+sudo systemctl stop infisical-gateway # Stop the service
+sudo systemctl status infisical-gateway # Check service status
+sudo systemctl disable infisical-gateway # Disable auto-start on boot
+```
- After installation, manage the service with standard systemd commands:
- ```bash
- sudo systemctl start infisical-gateway # Start the service
- sudo systemctl stop infisical-gateway # Stop the service
- sudo systemctl status infisical-gateway # Check service status
- sudo systemctl disable infisical-gateway # Disable auto-start on boot
- ```
diff --git a/docs/cli/commands/network.mdx b/docs/cli/commands/network.mdx
new file mode 100644
index 000000000..4e4cdbfe3
--- /dev/null
+++ b/docs/cli/commands/network.mdx
@@ -0,0 +1,441 @@
+---
+title: "infisical network"
+description: "Network-related commands for Infisical including gateway and proxy components"
+---
+
+
+
+ ```bash
+ infisical network gateway --token=
+ ```
+
+
+ ```bash
+ sudo infisical network gateway install --token= --domain= --name= --proxy-name=
+ ```
+
+
+
+## Description
+
+Network-related commands for Infisical that provide secure access to private resources through a three-tier proxy system:
+
+- **Gateway**: Lightweight agent deployed within your VPCs to provide access to private resources
+- **Proxy**: Identity-aware relay infrastructure that routes encrypted traffic (can be instance-wide or organization-specific)
+
+The gateway system uses SSH reverse tunnels over TCP, eliminating firewall complexity and providing excellent performance for enterprise environments.
+
+## Subcommands & flags
+
+
+ Run the Infisical gateway component within your VPC. The gateway establishes an SSH reverse tunnel to the specified proxy server and provides secure access to private resources.
+
+```bash
+infisical network gateway --proxy-name= --name= --auth-method=
+```
+
+The gateway component:
+
+- Establishes outbound SSH reverse tunnels to proxy servers (no inbound firewall rules needed)
+- Authenticates using SSH certificates issued by Infisical
+- Automatically reconnects if the connection is lost
+- Provides access to private resources within your network
+
+### Authentication
+
+The Infisical 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 Infisical. It requires a client ID and a client secret to authenticate with Infisical.
+
+
+
+
+ Your machine identity client ID.
+
+
+ Your machine identity client secret.
+
+
+ The authentication method to use. Must be `universal-auth` when using Universal Auth.
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=universal-auth --client-id= --client-secret= --proxy-name= --name=
+ ```
+
+
+
+ The Native Kubernetes method is used to authenticate with Infisical when running in a Kubernetes environment. It requires a service account token to authenticate with Infisical.
+
+
+
+
+ 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.
+
+
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=kubernetes --machine-identity-id= --proxy-name= --name=
+ ```
+
+
+
+ The Native Azure method is used to authenticate with Infisical when running in an Azure environment.
+
+
+
+
+ Your machine identity ID.
+
+
+ The authentication method to use. Must be `azure` when using Native Azure.
+
+
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=azure --machine-identity-id= --proxy-name= --name=
+ ```
+
+
+
+ The Native GCP ID Token method is used to authenticate with Infisical 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.
+
+
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=gcp-id-token --machine-identity-id= --proxy-name= --name=
+ ```
+
+
+
+ The GCP IAM method is used to authenticate with Infisical 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.
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=gcp-iam --machine-identity-id= --service-account-key-file-path= --proxy-name= --name=
+ ```
+
+
+
+ The AWS IAM method is used to authenticate with Infisical 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.
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=aws-iam --machine-identity-id= --proxy-name= --name=
+ ```
+
+
+
+ The OIDC Auth method is used to authenticate with Infisical 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.
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=oidc-auth --machine-identity-id= --jwt= --proxy-name= --name=
+ ```
+
+
+
+
+ The JWT Auth method is used to authenticate with Infisical 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.
+
+
+
+
+
+ ```bash
+ infisical network gateway --auth-method=jwt-auth --jwt= --machine-identity-id= --proxy-name= --name=
+ ```
+
+
+
+ You can use the `INFISICAL_TOKEN` environment variable to authenticate with Infisical with a raw machine identity access token.
+
+
+
+
+ The machine identity access token to use for authentication.
+
+
+
+
+ ```bash
+ infisical network gateway --token= --proxy-name= --name=
+ ```
+
+
+
+
+### Other Flags
+
+
+ The name of the proxy that this gateway should connect to. The proxy must be running and registered before starting the gateway.
+
+ ```bash
+ # Example
+ infisical network gateway --proxy-name=my-proxy --name=my-gateway --token=
+ ```
+
+ **Note:** If using organization proxies or self-hosted instance proxies, you must first start a proxy server using `infisical network proxy` before connecting gateways to it. For Infisical Cloud users using instance proxies, the proxy infrastructure is already running and managed by Infisical.
+
+
+
+
+ The name of the gateway instance.
+
+ ```bash
+ # Example
+ infisical network gateway --name=my-gateway --proxy-name=my-proxy --token=
+ ```
+
+
+
+
+ Domain of your self-hosted Infisical instance.
+
+ ```bash
+ # Example
+ infisical network gateway --domain=https://app.your-domain.com --proxy-name= --name=
+ ```
+
+
+
+
+
+ Install and enable the gateway as a systemd service. This command must be run with sudo on Linux.
+
+```bash
+sudo infisical network gateway install --token= --domain= --name= --proxy-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 Infisical.
+
+ ```bash
+ # Example
+ sudo infisical network gateway install --token= --name= --proxy-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 Infisical instance.
+
+ ```bash
+ # Example
+ sudo infisical network gateway install --domain=https://app.your-domain.com --name= --proxy-name=
+ ```
+
+
+
+
+ The name of the gateway instance.
+
+ ```bash
+ # Example
+ sudo infisical network gateway install --name=my-gateway --token= --proxy-name=
+ ```
+
+
+
+
+ The name of the proxy that this gateway should connect to.
+
+ ```bash
+ # Example
+ sudo infisical network gateway install --proxy-name=my-proxy --token= --name=
+ ```
+
+
+
+### Service Details
+
+The systemd service is installed with secure defaults:
+
+- Service file: `/etc/systemd/system/infisical-gateway.service`
+- Config file: `/etc/infisical/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 proxy
+- Handles certificate rotation and connection recovery automatically
+
+After installation, manage the service with standard systemd commands:
+
+```bash
+sudo systemctl start infisical-gateway # Start the service
+sudo systemctl stop infisical-gateway # Stop the service
+sudo systemctl status infisical-gateway # Check service status
+sudo systemctl disable infisical-gateway # Disable auto-start on boot
+```
+
+
+
+
+ Run the Infisical proxy component. The proxy handles network traffic routing and can operate in different modes.
+
+```bash
+infisical network proxy --type= --ip= --name= --auth-method=
+```
+
+### Flags
+
+
+ The type of proxy to run. Must be either 'instance' or 'org'.
+
+ - **`instance`**: Shared proxy server that can be used by all organizations on your Infisical instance. Set up by the instance administrator. Uses `INFISICAL_PROXY_AUTH_SECRET` environment variable for authentication, which must be configured by the instance admin.
+ - **`org`**: Dedicated proxy server that individual organizations deploy and manage in their own infrastructure. Provides enhanced security, custom geographic placement, and compliance benefits. Uses standard Infisical authentication methods.
+
+ ```bash
+ # Organization proxy (customer-deployed)
+ infisical network proxy --type=org --ip=192.168.1.100 --name=my-org-proxy
+
+ # Instance proxy (configured by instance admin)
+ INFISICAL_PROXY_AUTH_SECRET= infisical network proxy --type=instance --ip=10.0.1.50 --name=shared-proxy
+ ```
+
+
+
+
+ The public IP address of the instance where the proxy is deployed. This must be a static public IP that gateways can reach.
+
+ ```bash
+ # Example
+ infisical network proxy --ip=203.0.113.100 --type=org --name=my-proxy
+ ```
+
+
+
+
+ The name of the proxy.
+
+ ```bash
+ # Example
+ infisical network proxy --name=my-proxy --type=org --ip=192.168.1.100
+ ```
+
+
+
+### Authentication
+
+**Organization Proxies (`--type=org`):**
+Deploy your own proxy server in your infrastructure for enhanced security and reduced latency. Supports all standard Infisical authentication methods documented above in the gateway section.
+
+**Instance Proxies (`--type=instance`):**
+Shared proxy servers that serve all organizations on your Infisical instance. For Infisical Cloud, these are already running and ready to use. For self-hosted deployments, they're set up by the instance administrator. Authentication is handled via the `INFISICAL_PROXY_AUTH_SECRET` environment variable.
+
+```bash
+# Organization proxy with Universal Auth (customer-deployed)
+infisical network proxy --type=org --ip=192.168.1.100 --name=my-org-proxy --auth-method=universal-auth --client-id= --client-secret=
+
+# Instance proxy (configured by instance admin)
+INFISICAL_PROXY_AUTH_SECRET= infisical network proxy --type=instance --ip=10.0.1.50 --name=shared-proxy
+```
+
+### Deployment Considerations
+
+**When to use Instance Proxies (`--type=instance`):**
+
+- You want to get started quickly without setting up your own proxy infrastructure
+- You're using Infisical Cloud and want to leverage the existing proxy infrastructure
+- You're on a self-hosted instance where the admin has already set up shared proxies
+- You don't need custom geographic placement of proxy servers
+- You don't have specific compliance requirements that require dedicated infrastructure
+- You want to minimize operational overhead by using shared infrastructure
+
+**When to use Organization Proxies (`--type=org`):**
+
+- You need lower latency by deploying proxy servers closer to your resources
+- You have security requirements that mandate running infrastructure in your own environment
+- You have compliance requirements such as data sovereignty or air-gapped environments
+- You need custom network policies or specific networking configurations
+- You have high-scale performance requirements that shared infrastructure can't meet
+- You want full control over your proxy infrastructure and its configuration
+
+
diff --git a/docs/docs.json b/docs/docs.json
index 08121fa08..2f1bb225d 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -346,7 +346,10 @@
},
{
"group": "Architecture",
- "pages": ["internals/architecture/components", "internals/architecture/cloud"]
+ "pages": [
+ "internals/architecture/components",
+ "internals/architecture/cloud"
+ ]
},
"internals/security",
"internals/service-tokens"
@@ -564,7 +567,10 @@
"integrations/cloud/gcp-secret-manager",
{
"group": "Cloudflare",
- "pages": ["integrations/cloud/cloudflare-pages", "integrations/cloud/cloudflare-workers"]
+ "pages": [
+ "integrations/cloud/cloudflare-pages",
+ "integrations/cloud/cloudflare-workers"
+ ]
},
"integrations/cloud/terraform-cloud",
"integrations/cloud/databricks",
@@ -659,7 +665,9 @@
"documentation/platform/secret-scanning/overview",
{
"group": "Concepts",
- "pages": ["documentation/platform/secret-scanning/concepts/secret-scanning"]
+ "pages": [
+ "documentation/platform/secret-scanning/concepts/secret-scanning"
+ ]
}
]
},
@@ -709,13 +717,18 @@
"documentation/platform/ssh/overview",
{
"group": "Concepts",
- "pages": ["documentation/platform/ssh/concepts/ssh-certificates"]
+ "pages": [
+ "documentation/platform/ssh/concepts/ssh-certificates"
+ ]
}
]
},
{
"group": "Platform Reference",
- "pages": ["documentation/platform/ssh/usage", "documentation/platform/ssh/host-groups"]
+ "pages": [
+ "documentation/platform/ssh/usage",
+ "documentation/platform/ssh/host-groups"
+ ]
}
]
},
@@ -757,12 +770,17 @@
"cli/commands/export",
"cli/commands/token",
"cli/commands/service-token",
+ "cli/commands/network",
"cli/commands/vault",
"cli/commands/user",
"cli/commands/reset",
{
"group": "infisical scan",
- "pages": ["cli/commands/scan", "cli/commands/scan-git-changes", "cli/commands/scan-install"]
+ "pages": [
+ "cli/commands/scan",
+ "cli/commands/scan-git-changes",
+ "cli/commands/scan-install"
+ ]
}
]
},
@@ -1096,7 +1114,9 @@
"pages": [
{
"group": "Kubernetes",
- "pages": ["api-reference/endpoints/dynamic-secrets/kubernetes/create-lease"]
+ "pages": [
+ "api-reference/endpoints/dynamic-secrets/kubernetes/create-lease"
+ ]
},
"api-reference/endpoints/dynamic-secrets/create",
"api-reference/endpoints/dynamic-secrets/update",