Configuration

A relay, a workspace, and the right credentials.

Know where the pieces live.

Location	Purpose
`/etc/pepe/pepe.json`	Private relay configuration and generated credentials
`/var/lib/pepe/pepe.sqlite`	Workspaces, PR ownership, queued events, OAuth transactions
`/etc/caddy/pepe.caddy`	The relay's HTTPS reverse proxy

The configuration file looks like this. The installer supplies real random credentials; placeholders below are only examples.

{
  "listen": "127.0.0.1:8080",
  "public_url": "https://pepe.example.com",
  "database": "/var/lib/pepe/pepe.sqlite",
  "admin_token": "<your-private-random-admin-token>",
  "webhook_secret": "<your-private-random-github-webhook-secret>"
}

Both secrets must be at least 32 characters. Keep this file private and out of Git. Restart pepe.service after a configuration change. The current relay is single-operator: anyone holding the admin token is trusted to register workspaces. Use separate relays for mutually untrusted groups.

Run in the foreground instead

For a local smoke test:

export PEPE_ADMIN_TOKEN="$(openssl rand -hex 32)"
export PEPE_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
pepe serve --public-url http://localhost:8080 --db ./pepe.sqlite

Public providers cannot reach this local-only example without an externally reachable HTTPS endpoint. pepe serve --config ./pepe.json uses the JSON configuration instead of the environment/flag defaults.

Connect a workspace.

On a trusted development machine, supply your relay URL and its admin token, then start the agent:

export PEPE_SERVER=https://pepe.example.com
printf "Pepe admin token: "
read -rs PEPE_ADMIN_TOKEN
printf "\n"
export PEPE_ADMIN_TOKEN
pepe run --target http://127.0.0.1:3000/api/github/webhook

The first run creates .pepe/identity.json with a workspace ID and session token. Add .pepe/ to your application’s .gitignore. Keep that identity across restarts; give separate workspaces separate identities.

The command prints your branch prefix. For example:

Pepe connected · p_24b3a4c5d6e7
Branch prefix: pepe/p_24b3a4c5d6e7/

Create your work under that prefix:

git switch -c pepe/p_24b3a4c5d6e7/fix-login

Provisioning disposable or shared machines? Keep the admin token on the controller. Register each workspace through POST /sessions and pass only its own session token to a custom relay client. The current pepe run command requires the admin token for registration; it is intended for trusted machines.