Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

6.6 KB
Raw Blame
---
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