Skip to main content
skill CX Codex

infisical-gateway — Claude Code skill: what it does, how to install

A setup skill for Infisical Gateway and Relay: it gets the platform to databases, directories and APIs that sit behind a firewall. Useful when Infisical reports it cannot reach an internal resource.

MIT 238 installs ★ 41 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Infisical/ai-skills --skill infisical-gateway -a claude-code
Open on GitHub

What infisical-gateway does

The assistant takes over one narrow job: making a private resource reachable from Infisical. That means a database with no public endpoint, an on-prem directory or an internal API. Gateway is installed inside your own network and dials outward, so nothing has to be opened inbound.

The skill works through a short checklist. Confirm the resource is genuinely private, count the isolated networks (each one needs its own gateway), pick a relay that Infisical manages or one you deploy, enroll the gateway with infisical gateway start or infisical gateway systemd, then verify egress. It carries the exact ports: TCP 2222 to the relay, TCP 443 to Infisical, TCP 8443 from platform to relay. Traffic rides an SSH reverse tunnel authenticated with certificates, and the relay only routes it. A blocked outbound 2222 keeps the tunnel from forming, so egress gets checked before the config.

Two reference files come with it: references/deployment-and-networking.md for deployment and networking, references/pools-and-consumers.md for pools and which consumers accept a gateway. Gateway is a paid Enterprise feature. Only 16 App Connection types take a gatewayId, and pairing it with gatewayPoolId fails validation. For production a pool is the safer shape, because a lone gateway is a single point of failure for every feature routed through it. Gateways send health every 3 minutes, relays hourly.

What it helps with

  • reach a VPC-only database from Infisical
  • work out how many gateways separate prod and staging networks need
  • check egress rules before a deployment stalls
  • run the gateway under systemd on an internal host
  • replace a lone gateway with a pool for production

Example prompts for the agent

  • Infisical can't reach our internal Postgres in the VPC. Walk me through the Gateway and list the outbound ports I need.
  • Deploy the gateway on the on-prem host with infisical gateway systemd and explain what the relay actually does.
  • How many gateways do I need if prod and staging live in separate networks?

How to install infisical-gateway

1Skills CLI (Vercel)

npx skills add Infisical/ai-skills --skill infisical-gateway -a claude-code

2Manually: put the files in place

~/.claude/skills/infisical-gateway/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/infisical-gateway/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about infisical-gateway

How do I install infisical-gateway in Claude Code?

Run npx skills add Infisical/ai-skills --skill infisical-gateway -a claude-code. The skill ends up at ~/.claude/skills/infisical-gateway/SKILL.md.

What does infisical-gateway do?

It guides an agent through Infisical Gateway and Relay setup so the platform can reach resources with no public endpoint: counting isolated networks, checking egress, handing over the deployment commands.

Which ports does the gateway need?

Outbound only: TCP 2222 to the relay, TCP 443 to Infisical and TCP 8443 from the platform to the relay. No inbound rules.

Source text

SKILL.md · MIT
---
name: infisical-gateway
description: "Guide for the Infisical Gateway and Relay — reaching private network resources (VPC-only databases, on-premises directories, internal APIs, HSMs) from Infisical without any inbound firewall rules. Covers the gateway/relay architecture using SSH reverse tunnels, exact ports and egress allowlist requirements (TCP 2222 to the relay, TCP 443 to Infisical, TCP 8443 platform-to-relay), deployment with `infisical gateway start` and `infisical gateway systemd`, Infisical-managed vs self-deployed relays, Gateway Pools for high availability, health checks and heartbeat intervals, and which features and App Connection types can be routed through a gateway. Use this skill when someone asks about: Infisical Gateway, relay server, accessing a private database from Infisical, dynamic secrets for a database with no public endpoint, gateway pools, or 'Infisical cannot reach my internal resource'. A Gateway is not a substitute for self-hosting (infisical-self-host) and not an App Connection (infisical-app-connections) — private resources need both a gateway and a connection."
---
# Infisical Gateway Guide

You are a setup assistant helping users reach private network resources from Infisical.

The problem the Gateway solves: Infisical needs to talk to a database, directory, or API that has no
public endpoint. The Gateway is a lightweight service you run **inside** your network that makes only
**outbound** connections, so no inbound firewall rules are needed.

Gateway is a **paid Enterprise** feature.

## Not this skill

The Gateway is a piece of shared plumbing, not a feature in itself. Users usually arrive because
something else cannot reach a resource:

| If the user wants... | Use, then come back here for the gateway |
|----------------------|------------------------------------------|
| Dynamic credentials for a private database | `infisical-dynamic-secrets` |
| An App Connection to a private host | `infisical-app-connections` |
| To rotate a credential on an internal system | `infisical-secret-rotation` |
| PAM sessions to internal infrastructure | `infisical-pam` |
| An internal CA (ADCS, Venafi) or an HSM | `infisical-pki` |
| To sync certificates to an on-prem load balancer | `infisical-pki` |
| A KMIP server | `infisical-kms` |
| To self-host Infisical itself | `infisical-self-host` |

**A Gateway is not a substitute for self-hosting.** Users sometimes think reaching private resources
requires self-hosting Infisical. It does not — that is precisely what the Gateway is for. Cloud
Infisical plus a Gateway reaches private resources without moving the platform.

**A Gateway is also not an App Connection.** The gateway provides the network path; the connection
provides the credentials. Private resources need both.

## Architecture

Two components:

| Component | Where it runs | What it does |
|-----------|--------------|--------------|
| **Gateway** | Inside **your** network | Proxies Infisical's requests to your private resources. Outbound-only |
| **Relay server** | Infisical-managed, or self-deployed | Routes encrypted traffic between the platform and your gateway. Never decrypts it |

The flow uses **SSH reverse tunnels with certificate-based authentication**:

1. **Registration** — the gateway opens an outbound SSH reverse tunnel to a relay, using SSH certificates issued by Infisical
2. **Persistent connection** — the gateway holds that TCP connection open, creating a channel for inbound requests
3. **Routing** — when the platform needs your resource, the request goes through the relay and down the existing tunnel
4. **Access** — the gateway connects to the private resource on Infisical's behalf

Traffic through the relay is **double-encrypted**, and the relay routes only — it cannot decrypt.

## The rule about network placement

**A gateway must sit in the same network as the resources it reaches, with direct connectivity to
them.** Separate networks, regions, or isolated environments each need their **own** gateway.

This is the most common design mistake: one gateway is expected to cover a whole estate. If the user
has a prod VPC and a staging VPC with no route between them, that is two gateways.

## How to use this skill

1. **Confirm a gateway is actually needed** — is the resource genuinely unreachable publicly?
2. **Count the networks** — one gateway per isolated network
3. **Decide relay strategy** — Infisical-managed (simplest) or self-deployed (lower latency)
4. **Deploy the gateway** and enroll it
5. **Verify the egress allowlist** — this is where deployments stall
6. **Attach the gateway** to the consuming connection or feature
7. **Consider a Gateway Pool** for production HA

## Reference files

| File | When to read |
|------|-------------|
| `references/deployment-and-networking.md` | Deploying gateways and relays, exact ports and egress rules, systemd, health checks, troubleshooting |
| `references/pools-and-consumers.md` | Gateway Pools for HA, which features and connection types accept a gateway |

## Guiding principles

- **No inbound ports, ever.** If a user is opening inbound firewall rules for a gateway, they have misunderstood the model. The gateway dials out.
- **One gateway per isolated network.** Not one per resource, and not one for everything.
- **Only 16 App Connection types accept a gateway.** Passing `gatewayId` to any other type is a validation error, not a no-op. See `infisical-app-connections`.
- **`gatewayId` and `gatewayPoolId` are mutually exclusive.** Specifying both fails.
- **Use a Gateway Pool for anything production.** A single gateway is a single point of failure for every feature routed through it.
- **Check egress before debugging anything else.** Most "gateway won't connect" reports are a blocked outbound port.
- **Gateways report health every 3 minutes; relays hourly.** Know the intervals before concluding something is down.

© Infisical · MIT · Infisical/ai-skills

Similar skills

All skills for Security →

From the same set17

The whole set →
infisical-secret-rotation infisical-secret-rotation guides the setup of periodic credential replacement across 28 providers, writing updated values directly back to Infisical. CX Codex +1 255installs infisical-secret-scanning Sets an agent up with Infisical Secret Scanning: repo data sources, the infisical scan CLI, pre-commit hooks and tuning to cut noise. CX Codex +1 254installs infisical-kms A guide that walks the agent through Infisical KMS: encrypt, decrypt, sign, verify and HMAC with keys that never leave the platform. CX Codex +1 238installs infisical-pam Guides setup for brokering human and AI agent infrastructure access via Infisical PAM without revealing credentials. CX Codex +1 238installs infisical-sso infisical-sso — a skill that walks you through connecting Infisical to an identity provider (Google, GitHub, Okta, Azure AD, SAML, OIDC, or LDAP) for human login and automatic account creation. CX Codex +1 237installs infisical-pki infisical-pki guides the setup of Infisical Certificate Management, from issuing X.509 leaf certificates to configuring CAs and syncing with cloud vaults. CX Codex +1 235installs infisical-kubernetes-operator Walks you through the Infisical Kubernetes Operator: secrets synced into Secrets and ConfigMaps, pushed back out, dynamic leases kept in-cluster. CX Codex +1 223installs infisical-setup This Claude Code and Codex skill guides Infisical setup for delivering secrets to apps, containers, and CI/CD. It selects steps for CLI, SDK, Docker, Kubernetes, or machine authentication tasks. CX Codex +1 163installs

Project sponsors

Companies that keep this analytics open