Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
---
title: "PAM local development"
description: "Set up a gateway for local PAM 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.
<Note>
If you haven't set up the Infisical platform yet, follow the [local development guide](/contributing/platform/developing) first.
</Note>
## 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.
```mermaid
graph LR
subgraph Docker ["Docker (localhost:8080)"]
Backend["Infisical Backend"]
DB[("PostgreSQL")]
Redis["Redis"]
end
subgraph Host ["Host Machine (go run)"]
Gateway["Gateway<br/>(go run main.go gateway)"]
end
subgraph Local ["Local Resources"]
Target[("Local DB / Server")]
end
Backend <-->|"host.docker.internal:8443 · mTLS"| Gateway
Gateway <--> Target
```
| Component | Where it runs | What it does |
|-----------|---------------|--------------|
| **Infisical Platform** | Docker | Backend API, database, Redis |
| **Gateway** | Host machine | Proxies connections to local resources |
<Note>
The gateway listens on `host.docker.internal` so the Dockerized backend can reach it on your host machine.
</Note>
For more details on the production architecture, see:
- [Gateway Overview](/documentation/platform/gateways/overview)
- [PAM Architecture](/documentation/platform/pam/architecture)
## Prerequisites
- Infisical platform running locally via `docker compose -f docker-compose.dev.yml up`
- [Go](https://golang.org/dl/) installed
- A machine identity with Token Auth configured (see [Token Auth docs](/documentation/platform/identities/token-auth))
## Clone the CLI repository
The gateway lives in the [Infisical CLI repository](https://github.com/Infisical/cli). For local development, run it via `go run main.go` rather than the pre-built binary:
```bash
git clone https://github.com/Infisical/cli.git
cd cli
```
## Start the Gateway
From the CLI repository root:
```bash
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](/cli/reference#gateway-start).
<Accordion title="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`:
```bash
go run main.go relay start \
--name=local-relay \
--token=<your-token> \
--domain=http://localhost:8080 \
--host=host.docker.internal
```
```bash
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](/cli/reference#relay-start) for all flags.
</Accordion>
## 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`](https://github.com/infisical/cli/tree/main/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.
```env
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](https://github.com/infisical/cli/blob/main/dev/pam/README.md) 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
<AccordionGroup>
<Accordion title="Gateway cannot connect to Infisical">
Ensure the backend is fully started before running the gateway. Check logs:
```bash
docker compose -f docker-compose.dev.yml logs -f backend
```
</Accordion>
<Accordion title="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
</Accordion>
<Accordion title="Cannot reach local resources through gateway">
- Check resource connection details are correct
- Ensure target resource is running and accessible from your machine
</Accordion>
</AccordionGroup>
## Next steps
- [Launch your first session](/documentation/platform/pam/quick-starts/launch-first-session) and test connections through the gateway
- Explore [session recording](/documentation/platform/pam/sessions/session-recording) functionality