Skip to main content
This guide covers setting up the relay and gateway components for local PAM (Privileged Access Management) development. It assumes you already have the Infisical platform running locally.
If you haven’t set up the Infisical platform yet, follow the local development guide first.

​
Local Development Setup

In a local dev environment, the Infisical platform runs inside Docker while the relay and gateway run directly on your host machine:
ComponentWhere it runsWhat it does
Infisical PlatformDockerBackend API, database, Redis
Relay ServerHost machineRoutes traffic between backend and gateway
GatewayHost machineProxies connections to local resources
The relay uses host.docker.internal so the Dockerized backend can reach it on your host machine.
For more details on the production architecture, see:

​
Prerequisites

  • Infisical platform running locally via docker compose -f docker-compose.dev.yml up
  • Go installed
  • A machine identity with Token Auth configured (see Token Auth docs)

​
Clone the CLI Repository

The relay and gateway live in the Infisical CLI repository. For local development, run them via go run main.go rather than the pre-built binary: 
git clone https://github.com/Infisical/cli.git
cd cli

​
Start the Relay Server

From the CLI repository root: 
go run main.go relay start \
  --name=local-relay \
  --token=<your-token> \
  --domain=http://localhost:8080 \
  --host=host.docker.internal
Use host.docker.internal because the Infisical backend runs inside Docker and needs to reach the relay on your host machine.
Verify registration at Organization Settings > Networking > Relays. For all available flags, see the Relay CLI Reference.

​
Start the Gateway

In a new terminal, from the CLI repository root: 
go run main.go gateway start \
  --token=<your-token> \
  --domain=http://localhost:8080 \
  --target-relay-name=local-relay \
  --name=local-gateway \
  --pam-session-recording-path=$(pwd)/session
Verify registration at Organization Settings > Networking > Gateways. For all available flags, see the Gateway CLI Reference.

​
Quick Reference

ComponentCommand
Relaygo run main.go relay start --name=local-relay --token=<token> --domain=http://localhost:8080 --host=host.docker.internal
Gatewaygo run main.go gateway start --token=<token> --domain=http://localhost:8080 --target-relay-name=local-relay --name=local-gateway --pam-session-recording-path=$(pwd)/session

​
Troubleshooting

Ensure the backend is fully started before running relay/gateway. Check logs:
docker compose -f docker-compose.dev.yml logs -f backend
  • Verify relay is running and registered in the UI
  • Check --target-relay-name matches relay’s --name
  • Ensure port 2222 is not blocked
  • Check resource connection details are correct
  • Ensure target resource is running and accessible from your machine

​
Next Steps