FrontGate

Because pip install shouldn't blindly trust the public internet.

FrontGate is a Go-based, policy-enforcing reverse proxy that sits between your Python clients (pip, uv, Poetry) and upstream indexes like PyPI. It evaluates supply chain security policies at resolution time and filters disallowed package versions before they reach your resolver. No artifact storage. No private registry. Just a policy layer.

It is aimed at platform and security teams that need central dependency policy for many services, not a replacement for pip, uv, Poetry, or PyPI.

• Product vision: PRODUCT.md
• Backlog & roadmap: BACKLOG.md
• Architecture: ARCHITECTURE.md
• Client integration guides: docs/integrations/README.md
• Agent workflow & standards: AGENTS.md
• Contribution guide: CONTRIBUTING.md

Running the proxy locally

go run ./cmd/frontgate -config config/default.yaml

The default config listens on :8080. Once running:

• curl localhost:8080/healthz returns ok for readiness checks.
• curl localhost:8080/simple/pip/ responds with a PEP 503-compliant HTML index filtered by policy.
• curl localhost:8080/metrics returns Prometheus metrics.
• Local e2e helpers live in scripts/e2e/run.sh and the thin wrappers scripts/e2e/pip.sh, scripts/e2e/poetry.sh, and scripts/e2e/uv.sh.
• Named e2e cases are defined in testdata/e2e/matrix.yaml. Run one case with scripts/e2e/run.sh <tool> --case <name> or all cases by default.

Policy configuration

Point the proxy at a policy YAML file to enable enforcement:

# config/policy.yaml
version: 1
mode: permissive

global:
  policies:
    - name: cooldown
      action: deny
      match:
        release_age_days: "<7"
      reason: "7-day cooldown on new releases"

Then start with:

go run ./cmd/frontgate -config config/default.yaml

Add policy.file: config/policy.yaml to your config file, or pass a custom config. Without a policy file the proxy runs in pass-through mode (allow all).

Client Integration Guides

Phase 3 documentation lives under docs/integrations/:

• pip
• Poetry
• uv
• CI examples
• Use scripts/e2e/run.sh <tool> --case <name> --observe to start Grafana and Prometheus for manual metric inspection on one selected case.

Superpowers Plugin

This project uses the superpowers Claude Code plugin, which provides structured development workflow skills. Install it once:

/plugin install superpowers@claude-plugins-official
/reload-plugins

Available skills

Skill	When to use
superpowers:brainstorming	Before any feature, component, or behavior change — explores requirements and design
superpowers:writing-plans	When you have a spec or multi-step task — produces a reviewable implementation plan
superpowers:executing-plans	When executing an approved plan — runs phases with mandatory review checkpoints
superpowers:test-driven-development	Before writing implementation code — writes tests first
superpowers:systematic-debugging	When you hit a bug or test failure — diagnoses root cause before proposing fixes
superpowers:dispatching-parallel-agents	When you have 2+ independent tasks — fans them out to parallel agents
superpowers:subagent-driven-development	Executing plans with independent tasks in the current session
superpowers:using-git-worktrees	Before feature work that needs isolation — creates a dedicated worktree
superpowers:requesting-code-review	When implementation is complete — verifies work meets requirements
superpowers:receiving-code-review	When acting on review feedback — ensures technically sound responses
superpowers:finishing-a-development-branch	When all tests pass and work is ready to integrate
superpowers:verification-before-completion	Before claiming work is done — runs verification commands and confirms output
superpowers:writing-skills	When creating or editing skills — ensures they work before deployment

Typical workflow

brainstorming → writing-plans → [plan approval] → executing-plans
                                                        ↓
                                          verification-before-completion
                                                        ↓
                                        finishing-a-development-branch

Skills are invoked automatically when the task matches their trigger, or explicitly via the Skill tool. See superpowers:using-superpowers for how the plugin selects skills.

Configuration

config/default.yaml ships with sensible development defaults:

• server: listen address + graceful shutdown timeout.
• logging: slog text handler level.
• upstream: PyPI base URL, HTTP timeout, and User-Agent used by the upstream client.
• cache: TTL (seconds) before cached metadata is considered stale.
• mirror: background worker refresh interval for opportunistic re-fetching.
• policy: path to a policy YAML file. When unset, the proxy runs in pass-through mode.

Override any value via a custom YAML file and point the binary at it with -config path/to/file.yaml.

Superpowers Plugin

This project uses the Superpowers plugin for Claude Code.

Typical workflow

              ┌─ systematic-debugging (on any bug or test failure)
              │
brainstorming → writing-plans → [plan approval] → executing-plans
                                                        │
                                         ┌──────────────┴──────────────┐
                               test-driven-development    verification-before-completion
                                                                        │
                                                       finishing-a-development-branch