Pomerium

https://www.pomerium.com/docs
Admin
Pomerium is an open-source identity-aware proxy built on BeyondCorp and zero-trust principles,...
Tokens:187,751
Snippets:2,779
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Enable Pomerium Enterprise (RPM)

Source: https://www.pomerium.com/docs/deploy/enterprise/install

Install the console package and start the system service.

```bash
yum -y install pomerium-console
```

```bash
sudo systemctl enable --now pomerium-console
```

--------------------------------

### Install and Enable Pomerium Enterprise (DEB)

Source: https://www.pomerium.com/docs/deploy/enterprise/install

Update package lists, install the console, and start the system service.

```bash
sudo apt update; sudo apt install pomerium-console
```

```bash
sudo systemctl enable --now pomerium-console
```

--------------------------------

### Deploy the JIT Example Stack

Source: https://www.pomerium.com/docs/guides/jit

Commands to clone the repository and start the application stack using Docker Compose.

```bash
git clone https://github.com/pomerium/jit-example
# save the Compose file above as docker-compose.yaml in this directory
docker compose up -d
```

--------------------------------

### Start Local Docker Stack

Source: https://www.pomerium.com/docs/guides/ssh-tcp-l4-passthrough

Initialize the local example stack using Docker Compose.

```bash
docker compose up -d --build
docker compose ps
```

--------------------------------

### Install Enterprise Client Libraries

Source: https://www.pomerium.com/docs/internals/management-api-enterprise

Commands to install the required client libraries for Python and Go.

```bash
pip3 install git+https://git@github.com/pomerium/enterprise-client-python
```

```bash
go install github.com/pomerium/enterprise-client-go@latest
```

--------------------------------

### Enable and Start Pomerium Service

Source: https://www.pomerium.com/docs/deploy/core

Enables the service to start on boot and initiates it immediately.

```bash
sudo systemctl enable --now pomerium.service
```

--------------------------------

### Install and Configure mkcert

Source: https://www.pomerium.com/docs/get-started/fundamentals/core/tcp-routes

Commands to install the local CA and generate wildcard certificates for development.

```sh
mkcert -install
```

```sh
`mkcert "*.localhost.pomerium.io"`
```

--------------------------------

### Install Pomerium on Linux with Token

Source: https://www.pomerium.com/docs/internals/clusters

Use the installation script while providing the cluster token via an environment variable.

```bash
curl https://console.pomerium.app/install.bash | env POMERIUM_ZERO_TOKEN=<cluster_token> bash -s install
```

--------------------------------

### Install Pomerium Zero via Docker Compose

Source: https://www.pomerium.com/docs/deploy/cloud/install

Defines the Pomerium service and its dependencies in a compose file, then starts the containers.

```yaml
services:
  pomerium:
    image: pomerium/pomerium:latest
    ports:
      - 443:443
    restart: always
    environment:
      POMERIUM_ZERO_TOKEN: <CLUSTER_TOKEN>
      XDG_CACHE_HOME: /var/cache
    volumes:
      - pomerium-cache:/var/cache
    networks:
      main:
        aliases:
          - verify.<CLUSTER_STARTER_SUBDOMAIN>.pomerium.app
  verify:
    image: pomerium/verify:latest
    networks:
      main:
        aliases:
          - verify

networks:
  main: {}

volumes:
  pomerium-cache:
```

```bash
docker compose up -d
```

--------------------------------

### Deploy Service and Deployment

Source: https://www.pomerium.com/docs/deploy/k8s/gateway-api

Example service and deployment configuration for the httpbin application.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: httpbin
spec:
  selector:
    app: httpbin
  ports:
    - port: 80
      targetPort: 80
      name: http
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: httpbin-deployment
  labels:
    app: httpbin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: httpbin
  template:
    metadata:
      labels:
        app: httpbin
    spec:
      containers:
        - name: httpbin
          image: docker.io/kennethreitz/httpbin
          ports:
            - containerPort: 80
```

--------------------------------

### Install via RPM Package

Source: https://www.pomerium.com/docs/deploy/enterprise/install?method=kustomize

Commands to configure the repository and install the Pomerium Enterprise console on RHEL-based systems.

```bash
curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.rpm.sh' \
| sudo -E bash
```

```bash
yum install yum-utils pygpgme  
rpm --import 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key'  
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.rpm.txt?distro=el&codename=9' > /tmp/pomerium-enterprise.repo  
yum-config-manager --add-repo '/tmp/pomerium-enterprise.repo'  
yum -q makecache -y --disablerepo='*' --enablerepo='pomerium-enterprise'
```

```bash
yum -y install pomerium-console
```

```bash
sudo systemctl enable --now pomerium-console
```

--------------------------------

### Clone Documentation Repository

Source: https://www.pomerium.com/docs/guides/ssh-tcp-l4-passthrough

Prepare the local environment by cloning the repository and navigating to the example directory.

```bash
git clone https://github.com/pomerium/documentation
cd documentation/content/examples/ssh-tcp-l4-passthrough
```

--------------------------------

### Generate Demo Certificates

Source: https://www.pomerium.com/docs/guides/ssh-tcp-l4-passthrough

Create a local CA and server certificate for the example environment.

```bash
./gen-certs.sh
```

--------------------------------

### Install Pomerium CLI via Homebrew

Source: https://www.pomerium.com/docs/deploy/clients

Install the CLI on macOS using Homebrew.

```bash
brew install pomerium/tap/pomerium-cli
```

--------------------------------

### Install Argo CD via CLI

Source: https://www.pomerium.com/docs/guides/homelab-pipeline

Commands to create the namespace and apply the Argo CD installation manifests.

```bash
kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.3.6/manifests/install.yaml
```

--------------------------------

### Start pomerium-cli Listener

Source: https://www.pomerium.com/docs/guides/ssh-tcp-l4-passthrough

Run the pomerium-cli in the client container to establish the tunnel.

```bash
docker compose exec -d client sh -lc \
  'pomerium-cli tcp ssh.localhost.pomerium.io:22 \
    --alternate-ca-path /certs/ca.crt \
    --browser-cmd /bin/true \
    --listen 127.0.0.1:2222 \
    >/tmp/pomerium-cli.log 2>&1'
```

--------------------------------

### Resume installation

Source: https://www.pomerium.com/docs/guides/openclaw

Continue the bootstrap process if the script was interrupted or the directory already exists.

```bash
cd ./pomclaw
./bootstrap.sh
```

--------------------------------

### Install Pomerium Desktop via Homebrew

Source: https://www.pomerium.com/docs/deploy/clients

Install the Pomerium Desktop application on macOS using Homebrew.

```bash
brew install --cask pomerium/tap/pomerium-desktop
```

--------------------------------

### Install Pomerium via Package Manager

Source: https://www.pomerium.com/docs/deploy/core

Installs the Pomerium package using yum or apt.

```bash
# For yum-based systems:
yum install pomerium

# For apt-based systems:
apt-get update && apt-get install pomerium
```

--------------------------------

### Start an MCP Server

Source: https://www.pomerium.com/docs/capabilities/mcp/protect-mcp-server

Launch an MCP server using Docker Compose.

```bash
# Example: start one of the sample servers from the pomerium/mcp-servers repo
docker compose up -d
```

--------------------------------

### Apply Pomerium Zero Configuration

Source: https://www.pomerium.com/docs/deploy/k8s/sync-api

Applies the Kustomize configuration to start the Ingress Controller.

```bash
kubectl apply -k ic-zero/
```

--------------------------------

### Run the OpenClaw Install Script

Source: https://www.pomerium.com/docs/guides/openclaw

Executes the installation script to clone the repository and bootstrap the environment. The script defaults to the ./pomclaw directory.

```bash
curl -fsSL https://pomerium.com/docs/guides/code/openclaw/install.sh | bash
```

```bash
curl -fsSL https://pomerium.com/docs/guides/code/openclaw/install.sh | bash -s -- ~/openclaw
```

--------------------------------

### Install Pomerium Zero on Linux

Source: https://www.pomerium.com/docs/deploy/cloud/install

Uses the provided shell script to install Pomerium on a Linux server.

```bash
curl https://console.pomerium.app/install.bash | env POMERIUM_ZERO_TOKEN=<CLUSTER_TOKEN> bash -s install
```

--------------------------------

### Install required CLI tools

Source: https://www.pomerium.com/docs/guides/homelab-pipeline

Installs necessary utilities for managing Talos, Kubernetes, Terraform, and Helm via Homebrew.

```bash
brew install siderolabs/tap/talosctl
brew install kubectl
brew install hashicorp/tap/terraform
brew install kubeseal
brew install helm
```

--------------------------------

### Install via DEB Package

Source: https://www.pomerium.com/docs/deploy/enterprise/install?method=kustomize

Commands to configure the repository and install the Pomerium Enterprise console on Debian/Ubuntu systems.

```bash
curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.deb.sh' \
| sudo -E bash
```

```bash
apt-get install -y debian-keyring  # debian only  
apt-get install -y debian-archive-keyring  # debian only  
apt-get install -y apt-transport-https  

# For Debian Stretch, Ubuntu 16.04 and later  
keyring_location=/usr/share/keyrings/pomerium-enterprise-archive-keyring.gpg  

# For Debian Jessie, Ubuntu 15.10 and earlier  
keyring_location=/etc/apt/trusted.gpg.d/pomerium-enterprise.gpg  

curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key' |  gpg --dearmor >> ${keyring_location}  

curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.deb.txt?distro=debian&codename=wheezy&component=main' > /etc/apt/sources.list.d/pomerium-enterprise.list  

sudo chmod 644 ${keyring_location}  
sudo chmod 644 /etc/apt/sources.list.d/pomerium-enterprise.list  

apt-get update
```

```bash
sudo apt update; sudo apt install pomerium-console
```

```bash
sudo systemctl enable --now pomerium-console
```

--------------------------------

### Run Node.js Server

Source: https://www.pomerium.com/docs/get-started/fundamentals/core/advanced-routes

Command to start the Node.js application.

```bash
node index.js
```

--------------------------------

### SSH Command Examples

Source: https://www.pomerium.com/docs/capabilities/reverse-tunneling

Examples of using the SSH client to connect to Pomerium for reverse tunneling versus direct route access.

```bash
$ ssh -R ... pomerium.example.com
```

```bash
# The upstream server for the route 'some-ssh-route' handles the -R request here
$ ssh -R ... some-ssh-route@pomerium.example.com
```

--------------------------------

### Start OpenSSL Server

Source: https://www.pomerium.com/docs/internals/certificates-and-tls

Run an OpenSSL s_server instance to act as the upstream application.

```bash
openssl s_server \
  -key ./openssl.localhost-key.pem \
  -cert ./openssl.localhost.pem \
  -accept 44330 \
  -www
```

```bash
openssl s_server \
  -Verify 1 \
  -key ./openssl.localhost-key.pem \
  -cert ./openssl.localhost.pem \
  -accept 44330 \
  -www
```

--------------------------------

### Build Docker Containers

Source: https://www.pomerium.com/docs/get-started/fundamentals/core/advanced-routes

Command to build and start the Docker services.

```bash
docker compose up --build
```

--------------------------------

### Install local CA with mkcert

Source: https://www.pomerium.com/docs/internals/certificates-and-tls

Initializes a locally-trusted certificate authority for development environments.

```bash
mkcert -install
```

--------------------------------

### Install Gateway API and Pomerium Controller

Source: https://www.pomerium.com/docs/deploy/k8s/gateway-api

Commands to apply the necessary CRDs and install the Pomerium Ingress Controller via kustomization.

```sh
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml
```

```sh
kubectl apply -k github.com/pomerium/ingress-controller/config/gateway-api\?ref=0-33-0
```

--------------------------------

### Install Pomerium CLI via APT

Source: https://www.pomerium.com/docs/deploy/clients

Configure the Cloudsmith repository and install the CLI package on Debian or Ubuntu systems.

```bash
curl -1sLf \
  'https://dl.cloudsmith.io/public/pomerium/pomerium/setup.deb.sh' \
  | sudo -E bash

sudo apt-get update
sudo apt-get install pomerium-cli
```

--------------------------------

### Datasource Startup Output

Source: https://www.pomerium.com/docs/integrations/request-context/geoip

Expected console output when the datasource service starts successfully.

```sh
<nil> INF starting ip2location http server address=:8080 file=../IP2LOCATION-LITE-DB1.CSV.ZIP
```

--------------------------------

### Define Local Demo Route

Source: https://www.pomerium.com/docs/guides/ssh-tcp-l4-passthrough

Example route configuration for the local Docker environment.

```yaml
routes:
  - from: tcp+https://ssh.localhost.pomerium.io:22
    to: tcp://sshd:2222
    allow_public_unauthenticated_access: true
```

--------------------------------

### Setup Cloudsmith Repository

Source: https://www.pomerium.com/docs/deploy/core

Configures the package manager to use the Pomerium Cloudsmith repository.

```bash
curl -1sLf \
  'https://dl.cloudsmith.io/public/pomerium/pomerium/setup.deb.sh' \
  | sudo -E bash
```

--------------------------------

### Pomerium Route Configuration

Source: https://www.pomerium.com/docs/get-started/fundamentals/core/advanced-routes

Examples of defining routes in Pomerium, including prefix and prefix_rewrite settings.

```yaml
routes:
  - from: https://nodeserver.localhost.pomerium.io
    to: http://nodeserver:5001
    policy:
      allow:
        and:
          - domain:
              is: example.com
```

```yaml
- from: https://nodeserver.localhost.pomerium.io
    to: http://nodeserver:5001
    prefix: /admin
```

```yaml
- from: https://nodeserver.localhost.pomerium.io
    to: http://nodeserver:5001
    prefix: /admin
    prefix_rewrite: /
```

--------------------------------

### Initialize Docker files

Source: https://www.pomerium.com/docs/get-started/fundamentals/zero/zero-advanced-routes

Commands to create the Dockerfile and .dockerignore files.

```bash
touch Dockerfile && touch .dockerignore
```

--------------------------------

### Test API Connection with Go

Source: https://www.pomerium.com/docs/internals/management-api-enterprise

Example script demonstrating how to authenticate, list namespaces, find a policy, and create a route using the Go client.

```go
package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"os"

	pb "github.com/pomerium/enterprise-client-go/pb"

	client "github.com/pomerium/enterprise-client-go"
)

var serviceAccountToken = os.Getenv("SERVICE_ACCOUNT")
var target = "console-api.localhost.pomerium.io:443"

func main() {
	err := run()
	if err != nil {
		fmt.Printf("%s\n", err)
	}
}

func run() error {

	ctx := context.Background()

	tlsConfig := &tls.Config{InsecureSkipVerify: true}

	p, err := client.NewClient(ctx, target, serviceAccountToken, client.WithTlsConfig(tlsConfig))
	if err != nil {
		return fmt.Errorf("failed to connect: %w", err)
	}

	nsResp, err := p.NamespaceService.ListNamespaces(ctx, &pb.ListNamespacesRequest{})
	if err != nil {
		return fmt.Errorf("could not list namespaces: %w", err)
	}

	var productionNamespaceId string
	for _, n := range nsResp.GetNamespaces() {
		if n.GetName() == "Production" {
			productionNamespaceId = n.GetId()
		}
	}

	if productionNamespaceId == "" {
		return fmt.Errorf("could not find production namespace")
	}

	policyName := "my policy"
	var policyId string
	polResp, err := p.PolicyService.ListPolicies(ctx, &pb.ListPoliciesRequest{Namespace: productionNamespaceId, Query: &policyName})
	if err != nil {
		return fmt.Errorf("failed to find policy: %w", err)
	}
	if len(polResp.GetPolicies()) == 0 {
		return fmt.Errorf("no policy named '%s' found", policyName)
	}

	policyId = polResp.GetPolicies()[0].GetId()

	passIdHeaders := true
	newRoute := &pb.Route{
		NamespaceId:         productionNamespaceId,
		Name:                "my route",
		From:                "https://test.localhost.pomerium.io",
		To:                  []string{"https://verify.pomerium.com"},
		PolicyIds:           []string{policyId},
		PassIdentityHeaders: &passIdHeaders,
	}

	routeResp, err := p.RouteService.SetRoute(ctx, &pb.SetRouteRequest{Route: newRoute})
	if err != nil {
		return fmt.Errorf("could not create route: %w", err)
	}

	fmt.Printf("created route id: %s\n", routeResp.Route.GetId())
	return nil
}
```

--------------------------------

### Install Pomerium on Debian

Source: https://www.pomerium.com/docs/get-started/fundamentals/core/self-hosted-pomerium

Commands to add the Pomerium repository and install the package on a Debian-based system.

```sh
curl -1sLf \
'https://dl.cloudsmith.io/public/pomerium/pomerium/setup.deb.sh' \
| sudo -E bash
```

```sh
sudo apt install pomerium
```

--------------------------------

### Verify Pomerium CLI Installation

Source: https://www.pomerium.com/docs/get-started/fundamentals/core/tcp-routes

Check that the Pomerium CLI is correctly installed and accessible in your environment.

```shell-session
$ pomerium-cli
Usage:
  pomerium-cli [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  k8s         commands for the kubernetes credential plugin
  tcp         creates a TCP tunnel through Pomerium
  version     version

Flags:
  -h, --help      help for pomerium-cli
  -v, --version   version for pomerium-cli

Use "pomerium-cli [command] --help" for more information about a command.
```

--------------------------------

### Install Pomerium CLI via Binary

Source: https://www.pomerium.com/docs/deploy/clients

Download and extract the Pomerium CLI binary for a specific architecture and OS.

```bash
ARCH=[your-arch]
OS=[your-os]
VERSION=[desired-version]
curl -L https://github.com/pomerium/cli/releases/download/${VERSION}/pomerium-cli-${OS}-${ARCH}.tar.gz \
    | tar -z -x
```

--------------------------------

### Build Pomerium CLI from Source

Source: https://www.pomerium.com/docs/deploy/clients

Clone the repository and build the CLI binary locally.

```bash
git clone https://github.com/pomerium/cli.git
cd cli
make build
./bin/pomerium-cli --help
```

--------------------------------

### Install Argo Workflows via Helm

Source: https://www.pomerium.com/docs/guides/argo

Installs the Argo Workflows chart with server-side authentication mode enabled.

```bash
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update
kubectl create namespace argo
helm install argo argo/argo-workflows \
  --namespace argo \
  --set server.authModes='{server}'
```

--------------------------------

### Web Application Implementation

Source: https://www.pomerium.com/docs/internals/troubleshooting

Basic Go server and HTML/JS frontend for testing cross-domain requests.

```go
package main

import (
	"net/http"
)

func main() {
	http.Handle("/", http.FileServer(http.Dir(".")))
	http.ListenAndServe(":8000", nil)
}
```

```html
<!doctype html>
<html>
  <head>
    <title>Example Application</title>
    <script type="module" src="index.mjs"></script>
  </head>
  <body></body>
</html>
```

```javascript
(async () => {
  const result = await fetch('https://api.localhost.pomerium.io', {
    method: 'POST',
    headers: {
      Accept: 'application/json',
    },
  });
  const json = await result.json();
  console.log('RESULT', json);
})();
```

--------------------------------

### Kubernetes Forbidden Error Example

Source: https://www.pomerium.com/docs/capabilities/kubernetes-access

Example of the error message returned when a user lacks sufficient RBAC permissions.

```bash
$ kubectl get pods
Error from server (Forbidden): pods is forbidden: User "foo@example.com" cannot list resource "pods" in API group "" in the namespace "default"
```

--------------------------------

### Configure S3-Compatible Bucket URI

Source: https://www.pomerium.com/docs/capabilities/session-recording/storage

Example URI for S3-compatible storage like Minio, Ceph, or SeaweedFS.

```text
s3://mybucket?endpoint=http://my.minio.local:8080&disable_https=true&s3ForcePathStyle=true
```

--------------------------------

### Manage Factorio Server Processes

Source: https://www.pomerium.com/docs/capabilities/non-http/examples/factorio

Commands to create a new save file and start the Factorio headless server.

```bash
./bin/x64/factorio --create ./saves/pomerium-example.zip
```

```bash
./bin/x64/factorio --start-server ./saves/pomerium-example.zip
```

--------------------------------

### Test API Connection with Python

Source: https://www.pomerium.com/docs/internals/management-api-enterprise

Example script demonstrating how to authenticate, list namespaces, find a policy, and create a route using the Python client.

```python
#!/usr/bin/env python

import os
from pomerium.client import Client
from pomerium.pb.policy_pb2 import ListPoliciesRequest
from pomerium.pb.namespaces_pb2 import ListNamespacesRequest
from pomerium.pb.routes_pb2 import SetRouteRequest, Route

# get custom CA and service account credentials from environment
ca_cert = os.getenv('CA_CERT', '').encode('utf-8')
sa = os.getenv('SERVICE_ACCOUNT', '')
console_api = 'console-api.localhost.pomerium.io'

client = Client(console_api, sa, root_certificates=ca_cert)

# get id for namespace 'Production'
resp = client.NamespaceService.ListNamespaces(ListNamespacesRequest())
ns = [n for n in resp.namespaces if n.name == 'Production'][0]

# find policy named 'my policy' in namespace 'Production'
resp = client.PolicyService.ListPolicies(
    ListPoliciesRequest(query='my policy', namespace=ns.id)
)
policy = resp.policies[0]

# set route in namespace 'Production', associated to 'my policy'
route = Route(**{
    'namespace_id': ns.id,
    'name': 'my route',
    'from': 'https://test.localhost.pomerium.io',
    'to': ['https://verify.pomerium.com'],
    'policy_ids': [policy.id],
    'pass_identity_headers': True,
})

resp = client.RouteService.SetRoute(SetRouteRequest(route=route))
print(resp)
```

--------------------------------

### GCS Audit Log Metadata Example

Source: https://www.pomerium.com/docs/capabilities/session-recording/auditing

Example of the JSON metadata structure attached to GCS audit logs by Pomerium Enterprise.

```json
metadata: {
  audit_context: {
    app_context: "EXTERNAL"
      audit_info: {
        x-goog-custom-audit-pomerium-access-id: "b340be6f-d9d6-4569-9b8f-53d5fac8db0c"
        x-goog-custom-audit-pomerium-user: "PomeriumEnterprise/v0.32.0+0d0554ca+2026-05-25T11:06:03-04:00 (u=aw3iU61Z7p6wxCnNq/JVDgGHpJzhwT3eqs5Wmz8BPD8=)"
      }
    }
  requested_bytes: 1071492
  }
methodName: "storage.objects.get"
```

--------------------------------

### Start Docker Containers

Source: https://www.pomerium.com/docs/deploy/cloud/import

Run this command in your Docker project terminal to initialize the containers before executing the import command.

```bash
docker compose up
```

--------------------------------

### Configure DEB Repository Manually

Source: https://www.pomerium.com/docs/deploy/enterprise/install

Manually set up the repository by installing keys and adding the source list.

```bash
apt-get install -y debian-keyring  # debian only
apt-get install -y debian-archive-keyring  # debian only
apt-get install -y apt-transport-https
# For Debian Stretch, Ubuntu 16.04 and later
keyring_location=/usr/share/keyrings/pomerium-enterprise-archive-keyring.gpg
# For Debian Jessie, Ubuntu 15.10 and earlier
keyring_location=/etc/apt/trusted.gpg.d/pomerium-enterprise.gpg
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key' |  gpg --dearmor >> ${keyring_location}
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.deb.txt?distro=debian&codename=wheezy&component=main' > /etc/apt/sources.list.d/pomerium-enterprise.list
sudo chmod 644 ${keyring_location}
sudo chmod 644 /etc/apt/sources.list.d/pomerium-enterprise.list
apt-get update
```

--------------------------------

### GET /.pomerium/sign_out

Source: https://www.pomerium.com/docs/internals/special-routes

Logs the user out of Pomerium and optionally the identity provider.

```APIDOC
## GET /.pomerium/sign_out

### Description
Logs the user out of Pomerium, clears session cookies, and redirects to a post-logout page.

### Method
GET

### Endpoint
/.pomerium/sign_out

### Parameters
#### Query Parameters
- **pomerium_redirect_uri** (string) - Optional - The URL to redirect to after logout.
```

--------------------------------

### Create Pomerium Project Directory

Source: https://www.pomerium.com/docs/get-started/quickstart?type=zero

Create and navigate into a new directory for your Pomerium setup. This directory will hold your configuration files.

```bash
mkdir pomerium_quickstart  

cd pomerium_quickstart  
```

--------------------------------

### Display Pomerium Logs

Source: https://www.pomerium.com/docs/capabilities/audit-logs

Commands to view logs based on the installation method.

```bash
sudo journalctl -u pomerium.service
```

```bash
docker logs pomerium
```

```bash
kubectl logs -f deploy/pomerium-authorize
```

--------------------------------

### Define Route Configuration

Source: https://www.pomerium.com/docs/get-started/fundamentals/core/self-hosted-pomerium

Example of mapping an external domain to an internal service.

```yaml
- from: https://verify.domain.com
  to: https://verify.pomerium.com
```

--------------------------------

### GET /.well-known/pomerium

Source: https://www.pomerium.com/docs/internals/special-routes

Provides metadata about Pomerium's endpoints in a JSON format.

```APIDOC
## GET /.well-known/pomerium

### Description
Serves a JSON document containing metadata about Pomerium's endpoints, similar to an OpenID Connect Discovery document.

### Method
GET

### Endpoint
/.well-known/pomerium

### Response
#### Success Response (200)
- **issuer** (string) - Base URL of the Pomerium instance.
- **jwks_uri** (string) - URL to the JWKS endpoint.
- **authentication_callback_endpoint** (string) - OAuth2 callback URL.
- **frontchannel_logout_uri** (string) - URL for front-channel logout.
```

--------------------------------

### Start MCP Server Services

Source: https://www.pomerium.com/docs/capabilities/mcp/mcp-upstream-oauth

Command to initialize the MCP server environment using Docker Compose.

```bash
docker compose up -d
```

--------------------------------

### Tear down OpenClaw deployment

Source: https://www.pomerium.com/docs/guides/openclaw

Remove the deployment containers, volumes, and local installation directory.

```bash
cd ./pomclaw
docker compose down -v
```

```bash
rm -rf ./pomclaw
```

--------------------------------

### Pomerium installation output

Source: https://www.pomerium.com/docs/deploy/k8s/quickstart

Expected output after applying the Pomerium ingress controller configuration.

```text
namespace/pomerium created
customresourcedefinition.apiextensions.k8s.io/pomerium.ingress.pomerium.io created
serviceaccount/pomerium-controller created
serviceaccount/pomerium-gen-secrets created
clusterrole.rbac.authorization.k8s.io/pomerium-controller created
clusterrole.rbac.authorization.k8s.io/pomerium-gen-secrets created
clusterrolebinding.rbac.authorization.k8s.io/pomerium-controller created
clusterrolebinding.rbac.authorization.k8s.io/pomerium-gen-secrets created
service/pomerium-metrics created
service/pomerium-proxy created
deployment.apps/pomerium created
job.batch/pomerium-gen-secrets created
ingressclass.networking.k8s.io/pomerium created
```

--------------------------------

### Apply Kustomize Configuration

Source: https://www.pomerium.com/docs/deploy/enterprise/install?method=kustomize

Command to apply the local Kustomize configuration directory.

```bash
kubectl apply -k ./config
```

--------------------------------

### Configure DEB Repository Automatically

Source: https://www.pomerium.com/docs/deploy/enterprise/install

Use the setup script to automatically configure the repository for Debian and Ubuntu distributions.

```bash
curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.deb.sh' \
| sudo -E bash
```

--------------------------------

### Verify Datasource Readiness

Source: https://www.pomerium.com/docs/integrations/user-standing/bamboohr

Expected output indicating the datasource service has started successfully.

```json
{"level": "info", "message": "ready"}
```

--------------------------------

### Scaffold MCP Application

Source: https://www.pomerium.com/docs/capabilities/mcp/develop-mcp-app

Commands to clone the template repository and initialize the development environment.

```bash
git clone https://github.com/pomerium/chatgpt-app-typescript-template my-mcp-app
cd my-mcp-app
npm install
npm run dev
```

--------------------------------

### Run Ethr Server

Source: https://www.pomerium.com/docs/capabilities/non-http/examples/ethr

Start the Ethr server process to listen for incoming traffic.

```bash
ethr -s
```

--------------------------------

### Configure RPM Repository Manually

Source: https://www.pomerium.com/docs/deploy/enterprise/install

Manually set up the repository by importing keys and adding the repo configuration.

```bash
yum install yum-utils pygpgme
rpm --import 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key'
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.rpm.txt?distro=el&codename=9' > /tmp/pomerium-enterprise.repo
yum-config-manager --add-repo '/tmp/pomerium-enterprise.repo'
yum -q makecache -y --disablerepo='*' --enablerepo='pomerium-enterprise'
```

--------------------------------

### Prometheus PostgreSQL Metric Output

Source: https://www.pomerium.com/docs/reference/metrics

Example of a Prometheus metric output for the pgxpool_acquire_duration_nanoseconds_total counter.

```text
# HELP pomerium_pgxpool_acquire_duration_nanoseconds_total Total duration of all successful acquires from the pool in nanoseconds.
# TYPE pomerium_pgxpool_acquire_duration_nanoseconds_total counter
pomerium_pgxpool_acquire_duration_nanoseconds_total{db_client_connection_pool_name="localhost:5432/pomerium",db_system="postgresql",otel_scope_name="github.com/exaring/otelpgx",otel_scope_version="v0.9.1",hostname="my-host"} 5.1058702e+07
```

--------------------------------

### Start Pomerium UDP Tunnel

Source: https://www.pomerium.com/docs/capabilities/non-http/examples/ethr

Initiate the UDP tunnel using the Pomerium CLI on the client machine.

```bash
pomerium-cli udp ethr.corp.example.com:8888 --listen :8888
```

--------------------------------

### Block a Single Tool

Source: https://www.pomerium.com/docs/capabilities/mcp/reference

Example policy to deny access to a specific tool by name.

```yaml
policy:
  allow:
    and:
      - domain:
          is: company.com
  deny:
    and:
      - mcp_tool:
          is: drop_table
```

--------------------------------

### Build Pomerium Binary

Source: https://www.pomerium.com/docs/deploy/core

Compiles the Pomerium binary into the ./bin directory.

```bash
make
```

--------------------------------

### Example JWT Payload

Source: https://www.pomerium.com/docs/capabilities/mcp/reference

Represents the structure of the signed JWT contained in the X-Pomerium-Assertion header.

```json
{
  "email": "user@example.com",
  "groups": ["engineering", "admin"],
  "iss": "your-domain.com",
  "name": "John Doe",
  "sub": "user@example.com",
  "aud": "your-app.domain.com"
}
```

--------------------------------

### Configure RPM Repository Automatically

Source: https://www.pomerium.com/docs/deploy/enterprise/install

Use the setup script to automatically configure the repository for RHEL based distributions.

```bash
curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.rpm.sh' \
| sudo -E bash
```

--------------------------------

### GET /.pomerium/mcp/connect

Source: https://www.pomerium.com/docs/capabilities/mcp/delegate-mcp-to-llm

Initiates the upstream OAuth authentication flow for a specific MCP server.

```APIDOC
## GET /.pomerium/mcp/connect

### Description
Redirects the user to complete upstream authentication for an MCP server. Use this when a server shows `connected: false`.

### Method
GET

### Endpoint
https://<mcp-server-host>/.pomerium/mcp/connect

### Parameters
#### Query Parameters
- **redirect_url** (string) - Required - The URL to redirect to after successful authentication. Must match a configured MCP client route host.
```

--------------------------------

### Implement Widget Entry Point

Source: https://www.pomerium.com/docs/capabilities/mcp/develop-mcp-app

React component implementation using the App class to handle tool results and host context changes.

```tsx
function MyWidget() {
  const [toolOutput, setToolOutput] = useState(null);
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    const app = new App({name: 'MyWidget', version: '1.0.0'});
    app.ontoolresult = (result) =>
      setToolOutput(result.structuredContent ?? null);
    app.onhostcontextchanged = (context) => setTheme(context?.theme ?? 'light');
    app.connect();
  }, []);

  return (
    <div className={theme === 'dark' ? 'dark' : ''}>
      <h1>My Widget</h1>
      <pre>{JSON.stringify(toolOutput, null, 2)}</pre>
    </div>
  );
}

const rootElement = document.getElementById('my-widget-root');
if (rootElement) {
  createRoot(rootElement).render(
    <StrictMode>
      <MyWidget />
    </StrictMode>,
  );
}
```
Tokens:
Raw