Run and manage GitHub Actions self-hosted runner containers from a browser. Running Man uses a trusted forward-auth proxy for operator access and GitHub App Manifest flow for runner permissions. It does not require a GitHub PAT or pre-created OAuth App.
cp .env.example .env
# Set the required values described below.
docker compose up -dOpen APP_URL through your forward-auth proxy. On first use, open Settings
and choose Create and install GitHub App. GitHub creates an App for this
deployment and returns the browser to install it on the account or organization
that owns the runner pools. The generated private key is encrypted in the
Running Man SQLite volume, and the server exchanges it for short-lived
installation tokens as needed.
| Variable | Required | Default | Description |
|---|---|---|---|
APP_URL |
Yes | — | Browser-visible URL for GitHub App manifest callbacks, for example https://runners.example.com. |
APP_SECRET |
Yes | — | Stable random secret used to encrypt GitHub App credentials at rest. Generate with openssl rand -base64 32. Changing it requires creating and installing a new GitHub App. |
FORWARD_AUTH_ENABLED |
Yes | false |
Must be true to trust the identity injected by the reverse proxy. |
FORWARD_AUTH_HEADER |
No | Remote-User |
Proxy-injected operator identity header. Hola and Authelia commonly use this default; Authentik commonly uses X-authentik-username. |
GITHUB_APP_PUBLIC |
No | false |
Set to true before App creation when it must be installed on organizations beyond the App creator's account. |
PORT |
No | 3000 |
HTTP port listened to inside the container. |
BIND_ADDRESS |
No | 127.0.0.1 |
Host interface used by Compose port publishing. Keep this local-only when using forward auth. |
DATA_DIR |
No | /app/data |
Directory containing the persistent running-man.db database. |
DOCKER_SOCKET |
No | /var/run/docker.sock |
Docker socket path inside the container for local pools. |
LOG_LEVEL |
No | info |
Log level: debug, info, warn, or error. |
The proxy must strip FORWARD_AUTH_HEADER from all client requests and inject it
only after successful authentication. Do not expose the application directly to
the network while forward auth is enabled.
This repo ships a dev container based on the
node-agentic
template from get2knowio/devcontainer-templates.
Open the folder in VS Code and choose Dev Containers: Reopen in Container, or use the Dev Container CLI:
devcontainer up --workspace-folder .- Node.js 22 + Bun, Docker-in-Docker, AWS CLI, GitHub CLI, jq
- AI CLIs: Claude Code and Spec Kit (
specify) - Modern CLI tools (bat, ripgrep, fd, fzf, eza, zoxide, neovim, tmux, lazygit, …)
- Node tooling: TypeScript, Vite, esbuild, Prettier, ESLint, Biome
- GitHub Actions tooling: act, actionlint
The ai-clis feature is pinned to claudeCode,specifyCli to keep container builds fast.
To add others (Gemini CLI, Codex, Copilot, OpenCode, CodeRabbit, Beads), append them to the
install list in .devcontainer/devcontainer.json.