PAM local development

This guide covers setting up a gateway 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 gateway runs directly on your host machine. Use direct listen mode: the backend dials the gateway, so there’s no relay to run.

Component	Where it runs	What it does
Infisical Platform	Docker	Backend API, database, Redis
Gateway	Host machine	Proxies connections to local resources

The gateway listens on 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 gateway lives in the Infisical CLI repository. For local development, run it via go run main.go rather than the pre-built binary:

git clone https://github.com/Infisical/cli.git
cd cli

Start the Gateway

From the CLI repository root:

go run main.go gateway start \
  --token=<your-token> \
  --domain=http://localhost:8080 \
  --listen-address=host.docker.internal:8443 \
  --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.

Using a relay instead

Direct listen needs nothing else running, so prefer it unless you’re testing relay behaviour itself. For that, start a relay first and point the gateway at it with --target-relay-name instead of --listen-address:

go run main.go relay start \
  --name=local-relay \
  --token=<your-token> \
  --domain=http://localhost:8080 \
  --host=host.docker.internal

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 the relay at Organization Settings > Networking > Relays. See the Relay CLI Reference for all flags.

Quick reference

Component	Command
Gateway	`go run main.go gateway start --token=<token> --domain=http://localhost:8080 --listen-address=host.docker.internal:8443 --name=local-gateway --pam-session-recording-path=$(pwd)/session`

Seed test resources

Once your relay and gateway are up, you still need actual databases and SSH servers to point PAM at. Spinning those up by hand — running each container, creating users, then working through the UI to register every resource and account — is the slow part of any PAM dev loop. The dev/pam dev stack in the Infisical CLI repo does both in one shot: it boots the resources you pick in .env, pre-seeded with users and sample data, then registers each one as a PAM resource + account in your local Infisical against the gateway you just started.

ENABLE_POSTGRES=true
ENABLE_MYSQL=false
ENABLE_MSSQL=false
ENABLE_MONGODB=false
ENABLE_REDIS=true
ENABLE_SSH_PASSWORD=false
ENABLE_SSH_KEY=false

After make up, you get a connection table along with the CLI command and web access URL for each resource — no need to dig through the Infisical UI to grab them, just copy and use:

PAM dev stack — connection details:

resource              host       port   user       password       extras
postgres              127.0.0.1  55432  infisical  Infisical@123  db=infisical
redis                 127.0.0.1  55479  infisical  Infisical@123

Access snippets:
postgres (local01-2026-04-25-postgres / local01-2026-04-25-postgres-account)
  CLI:  go run main.go pam db access --resource ... --account ... --duration 1h
  Web:  http://localhost:8080/organizations/<org>/projects/pam/<project>/resources/postgres/<rid>/accounts/<aid>/access

Useful for faster development and reviews, reproducing issues, and testing across multiple resource types. See the dev/pam README for setup, env vars, and the full list of make targets. You’re not locked into this stack — PAM works against anything reachable from the gateway, so you can also point it at your own containers or cloud-hosted resources (DigitalOcean, AWS, etc.) when you need to test against something closer to production.

Troubleshooting

Gateway cannot connect to Infisical

Ensure the backend is fully started before running the gateway. Check logs:

docker compose -f docker-compose.dev.yml logs -f backend

Backend cannot reach the gateway

Check the gateway logs for “Direct gateway listener started”
Ensure --listen-address uses host.docker.internal, not localhost, so the Dockerized backend can reach your host
Ensure the port isn’t already in use

Cannot reach local resources through gateway

Check resource connection details are correct
Ensure target resource is running and accessible from your machine

Next steps

Launch your first session and test connections through the gateway
Explore session recording functionality

​Local development setup

​Prerequisites

​Clone the CLI repository

​Start the Gateway

​Quick reference

​Seed test resources

​Troubleshooting

​Next steps

Local development setup

Prerequisites

Clone the CLI repository

Start the Gateway

Quick reference

Seed test resources

Troubleshooting

Next steps