GO — Healthy across the board

• Last commit 1d ago
• 16 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Higress is an AI-native API gateway built on Istio and Envoy that routes and transforms requests to multiple LLM providers (OpenAI, Claude, Gemini, etc.) and hosts MCP (Model Context Protocol) servers. It extends Envoy with WebAssembly plugins written in Go/Rust/TypeScript and provides a web console for unified management of AI model APIs, request transformation, and agent tool hosting. Monorepo structure: core gateway logic in Go (main), plugins in plugins/wasm-go/extensions/ with provider implementations (ai-proxy folder), Envoy-based data plane in C++, and operational tools in .claude/skills/ (agent-session-monitor, higress-auto-router, nginx-to-higress-migration). The .claude/ directory contains AI-ready skill modules for common tasks like auto-routing and daily reporting.

Platform engineers and ML ops teams deploying AI applications who need centralized control over LLM API costs, request routing across model providers, and the ability to inject middleware logic (token counting, rate limiting, caching, prompt injection protection) without modifying application code.

Production-ready and actively maintained. The project is CNCF Sandbox-level, has comprehensive CI/CD via GitHub Actions, multi-language plugin support (Go, Rust, C++, TypeScript), and visible daily commits across core infrastructure. The .claude/skills directory indicates mature documentation and use-case scaffolding for real deployments.

Standard open source risks apply.

Active development on AI gateway features: multi-provider LLM routing (plugins/wasm-go/extensions/ai-proxy/provider/), MCP server integration (openclaw-integration skill), nginx migration tooling, and an auto-router skill for dynamic request routing. The agent-session-monitor and daily-report skills indicate focus on observability and governance for AI workloads.

Clone with git clone https://github.com/alibaba/higress.git && cd higress. Dependencies are Go 1.20+, Docker, and Make. Build the gateway with make build (inferred from Makefile in file list). For plugins, cd plugins/wasm-go/extensions/ai-proxy && go build. Run docker-compose up if a docker-compose.yaml exists in root (check README for exact commands).

Daily commands:

1. make build to compile gateway and plugins. 2. make docker-build for container images. 3. docker-compose up (if available) or deploy via Kubernetes manifests in deploy/ directory. 4. Access console at http://localhost:8080 (port inferred from typical Higress setups). Check .claude/skills/*/example/demo.sh for runnable examples.

• .claude/skills/higress-auto-router/SKILL.md — Defines the core auto-routing skill that powers Higress's model routing capabilities—essential for understanding the primary feature
• api/extensions/v1alpha1/wasmplugin.proto — Protocol buffer definition for WASM plugins; foundational API contract for extending Higress with custom logic
• .claude/skills/higress-wasm-go-plugin/SKILL.md — Documents WASM plugin development patterns in Go; critical for understanding how to build production plugins
• .claude/skills/nginx-to-higress-migration/SKILL.md — Migration framework for adopting Higress from Nginx; key reference for understanding Higress's positioning and compatibility layer
• .claude/skills/higress-openclaw-integration/SKILL.md — Integration patterns with OpenClaw; defines how Higress extends as an AI Gateway with model provider routing
• Makefile — Build orchestration entry point; reveals build system dependencies and project structure conventions
• VERSION — Single source of truth for semantic versioning across all artifacts and releases

Add a New WASM Plugin (Go)

1. Review WASM plugin development patterns and dependencies (.claude/skills/higress-wasm-go-plugin/SKILL.md)
2. Study HTTP client patterns for upstream communication (.claude/skills/higress-wasm-go-plugin/references/http-client.md)
3. Implement plugin Go code following local testing guide (.claude/skills/higress-wasm-go-plugin/references/local-testing.md)
4. Define plugin WASM configuration in wasmplugin.proto schema (api/extensions/v1alpha1/wasmplugin.proto)
5. Add GitHub Actions workflow for plugin image build and tests (.github/workflows/build-and-test-plugin.yaml)

Add a New Auto-Router Rule

1. Understand auto-routing skill architecture and configuration (.claude/skills/higress-auto-router/SKILL.md)
2. Extend model provider detection logic in OpenClaw integration (.claude/skills/higress-openclaw-integration/SKILL.md)
3. Add OpenClaw plugin extension to support new model provider (.claude/skills/higress-openclaw-integration/scripts/plugin/index.ts)
4. Update plugin configuration schema (.claude/skills/higress-openclaw-integration/scripts/plugin/openclaw.plugin.json)

Migrate from Nginx to Higress

1. Follow migration strategy and planning guidance (.claude/skills/nginx-to-higress-migration/SKILL.md)
2. Map Nginx annotations to Higress equivalents (.claude/skills/nginx-to-higress-migration/references/annotation-mapping.md)
3. Identify Nginx module equivalents in Higress plugins (.claude/skills/nginx-to-higress-migration/references/builtin-plugins.md)
4. Run analysis script on existing Nginx Ingress resources (.claude/skills/nginx-to-higress-migration/scripts/analyze-ingress.sh)

Add Session Monitoring

1. Understand session monitoring architecture and event model (.claude/skills/agent-session-monitor/SKILL.md)
2. Integrate session monitor into agent workflow (.claude/skills/agent-session-monitor/main.py)
3. Expose metrics via webserver interface (.claude/skills/agent-session-monitor/scripts/webserver.py)
4. Set up access log rotation and retention (.claude/skills/agent-session-monitor/example/test_rotation.sh)

• WASM (WebAssembly) plugins — Enables polyglot plugin development (Go, Rust, TinyGo) with sandboxing, performance, and safe cross-boundary calls without process overhead; critical for extending gateway behavior without recompilation
• Protocol Buffers (protobuf) — Provides versioned, language-agnostic schema for WASM plugin configuration and API contracts; enables forward/backward compatibility across releases
• OpenClaw integration — Abstracts multi-tenant AI provider routing; allows Higress to act as a unified control plane for heterogeneous LLM/ML model deployments
• Claude skills framework — Integrates AI-driven operational tasks (auto-routing, migration analysis, reporting) into the gateway; enables intelligent multi-step workflows without hardcoded logic
• Kubernetes Ingress + CRDs — Native cluster integration; allows GitOps-friendly declarative configuration via YAML rather than imperative config files

• WASM plugin model vs. embedded native plugins

  • Why: WASM provides isolation and language flexibility but incurs slight overhead vs. native code
  • Consequence: Lower latency for simple routing decisions is traded for broader ecosystem support and safer multi-tenant isolation

• Auto-routing via OpenClaw vs. static configuration

  • Why: AI-driven routing increases complexity but reduces operational burden of manual rule tuning
  • Consequence: Upfront investment in skill development yields long-term agility for model provider changes and cost optimization

• Kubernetes-native (CRDs) vs. standalone config

  • Why: Tighter Kubernetes integration improves GitOps workflows but adds hard dependency on Kubernetes control plane
  • Consequence: Simplified deployment in cloud-native orgs; less suitable for non-Kubernetes edge gateways

• Does not provide fine-grained AI model training or fine-tuning; only routes/manages existing model APIs

1. Wasm plugin sandboxing: plugins run in constrained Wasm environments; cannot use arbitrary Go stdlib features (no os.Exec, limited net). 2. Istio compatibility: version mismatches between Higress control plane and Istio can break CRD parsing; check version matrix in docs. 3. LLM provider auth: each ai-proxy provider requires specific header formats and auth schemes; token injection must match provider's exact specification or requests silently fail. 4. Plugin hot-reload: not all Wasm changes reload without gateway restart; some changes require full control-plane restart. 5. MCP server lifecycle: OpenClaw integration expects MCP servers to implement strict timeouts; slow responses may be terminated.

• WebAssembly (Wasm) Filters — Higress plugins run as Wasm modules in Envoy, enabling sandboxed, high-performance request transformation without recompiling the gateway; understanding Wasm constraints (memory limits, no arbitrary syscalls) is critical for plugin development.
• Model Context Protocol (MCP) — Higress hosts MCP servers to expose tools and services to AI agents; MCP is the standardized interface for connecting LLMs to external functions, making Higress a central hub for agent tooling.
• Istio Service Mesh — Higress control plane uses Istio-compatible CRDs (VirtualService, DestinationRule) for traffic management; familiarity with Istio's declarative traffic policies is necessary for advanced routing.
• Envoy Data Plane — Higress' underlying proxy; understanding Envoy's listener-filter-route architecture and xDS protocol helps debug networking issues and optimize performance.
• Token Counting & Rate Limiting — Higress plugins implement token-level accounting for LLM API costs (e.g., input/output tokens per request); rate limiting by model or user prevents cost overruns in multi-tenant deployments.
• Provider-Agnostic API Normalization — Different LLM providers (OpenAI, Claude, Gemini) use incompatible request/response formats; Higress normalizes these to a single interface, allowing seamless provider switching without app code changes.
• Kubernetes Custom Resource Definitions (CRDs) — Higress configuration (Routes, Upstreams, Plugins) is declared as Kubernetes CRDs; understanding how to write YAML manifests and debug CRD validation is essential for declarative deployments.

• istio/istio — Higress control plane is Istio-compatible; understanding Istio's CRD model and traffic management is essential
• envoyproxy/envoy — Higress data plane is built on Envoy; Wasm filter APIs and networking concepts derive from Envoy documentation
• hashicorp/consul — Alternative service mesh and API gateway; similar use cases for service discovery and request routing
• Kong/kong — Comparable open-source API gateway with plugin extensibility; different architecture (no Wasm, Lua-based) but overlapping gateway features
• Azure/api-management — Cloud alternative for AI model API management; use Higress for self-hosted equivalent

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for higress-openclaw-integration plugin

The higress-openclaw-integration skill has a TROUBLESHOOTING.md reference guide but lacks automated tests. The plugin integrates Higress with OpenClaw for AI model routing, which is critical functionality. Adding integration tests would ensure the plugin correctly handles model provider detection, region-specific routing, and fallback mechanisms. This is especially important given the detect-region.sh script exists but has no corresponding test coverage.

• [ ] Create .claude/skills/higress-openclaw-integration/tests/ directory with test files
• [ ] Write tests for the TypeScript plugin (index.ts) covering model provider initialization and routing logic
• [ ] Add GitHub Actions workflow in .github/workflows/ to run these integration tests on PR
• [ ] Document test setup and execution in .claude/skills/higress-openclaw-integration/SKILL.md

Add CI workflow validation for nginx-to-higress-migration scripts

The nginx-to-higress-migration skill contains critical migration tooling (analyze-ingress.sh, generate-migration-test.sh, generate-plugin-scaffold.sh) but there's no CI workflow validating these bash scripts. Shell scripts are prone to syntax errors and regressions. A linting and basic execution test workflow would ensure the migration tools remain functional across changes.

• [ ] Create .github/workflows/validate-migration-scripts.yaml to lint bash scripts with shellcheck
• [ ] Add basic smoke tests that execute the migration scripts with sample inputs from .claude/skills/nginx-to-higress-migration/scripts/
• [ ] Reference the migration scripts in the workflow and validate against both annotation-mapping.md and plugin-deployment.md requirements
• [ ] Document in .claude/skills/nginx-to-higress-migration/SKILL.md which scripts are covered by CI

Add end-to-end tests for agent-session-monitor with log rotation

The agent-session-monitor skill has multiple demo scripts (demo.sh, demo_v2.sh, test_rotation.sh) and test logs, but no automated test suite validating the session monitoring logic. The test_rotation.sh suggests log rotation is critical functionality. Creating a proper test suite would ensure log parsing, session tracking, and rotation handling work correctly across different log formats.

• [ ] Create .claude/skills/agent-session-monitor/tests/ directory with Python test files using pytest
• [ ] Write unit tests for main.py covering log parsing with both test_access.log and test_access_v2.log formats
• [ ] Write integration tests validating the session rotation logic from test_rotation.sh
• [ ] Add .github/workflows/test-agent-session-monitor.yaml to run pytest on every PR and main branch push

• Add a new LLM provider (e.g., Anthropic Bedrock, Aliyun Qwen) by copying plugins/wasm-go/extensions/ai-proxy/provider/openai.go, implementing the provider interface, and adding unit tests. Reference existing providers for auth header formats.
• Improve observability: extend agent-session-monitor/main.py to parse and expose additional metrics (e.g., token usage per model, provider latency percentiles) via the existing webserver.py Prometheus endpoint.
• Write E2E tests for nginx-to-higress migration: create test cases in .claude/skills/nginx-to-higress-migration/ that validate annotation-mapping.md transformations convert actual nginx Ingress resources to functionally equivalent Higress Routes.

• Medium · Missing package.json security metadata — .claude/skills/higress-openclaw-integration/scripts/plugin/package.json. The package.json file lacks essential security metadata including 'engines' field to specify Node.js version requirements, missing 'files' field to control published content, and no 'publishConfig' to restrict package visibility. This could allow unintended files to be published or installation on incompatible Node versions. Fix: Add 'engines': { 'node': '>=16.0.0' }, 'files': ['index.ts', '*.json'], and 'publishConfig': { 'access': 'public' } fields to package.json
• Medium · No dependency pinning or lock file detected — .claude/skills/higress-openclaw-integration/scripts/plugin/. The provided package.json has no version pinning strategy visible and no package-lock.json or yarn.lock file is referenced. This creates supply chain risks where dependency updates could introduce vulnerabilities without explicit control. Fix: Use exact version pinning (not ^, ~) for critical dependencies, maintain a lock file in version control, and regularly audit dependencies using 'npm audit' or 'yarn audit'
• High · Insecure shell script execution in automation — .claude/skills/agent-session-monitor/example/, .claude/skills/higress-daily-report/scripts/, .claude/skills/nginx-to-higress-migration/scripts/. Multiple shell scripts (.sh files) are present in the repository (demo.sh, test_rotation.sh, generate-report.sh, etc.) that may execute arbitrary commands. Without proper input validation and sandboxing, these could be vulnerable to command injection attacks, especially if they process user input or external data. Fix: Review all shell scripts for command injection vulnerabilities, avoid using eval() or similar functions, sanitize all user inputs, use shellcheck for static analysis, and consider rewriting critical automation in typed languages like Go or Python
• Medium · Unchecked dynamic plugin loading — .claude/skills/higress-openclaw-integration/scripts/plugin/package.json. The 'openclaw' configuration in package.json specifies dynamic extension loading via './index.ts' without apparent validation or sandboxing. This could allow malicious or vulnerable plugins to be loaded with full system access. Fix: Implement plugin signature verification, use sandboxed execution environments, validate plugin manifests against a schema, and restrict plugin capabilities using principle of least privilege
• Medium · Missing input validation in Python scripts — .claude/skills/agent-session-monitor/main.py, .claude/skills/agent-session-monitor/scripts/. Python scripts (main.py, cli.py, webserver.py) are present but without visibility into their implementation. Common risks include command injection, path traversal, and unsafe deserialization when handling user input or file operations. Fix: Implement strict input validation, use libraries like 'pathlib' for safe path operations, avoid pickle/eval for untrusted data, validate all HTTP inputs, and use security-focused linters
• High · Exposed example files with sensitive data patterns — .claude/skills/agent-session-monitor/example/. Example files (test_access.log, test_access_v2.log, test_rotation.sh) in the repository may contain or demonstrate handling of sensitive data. If these files are ever copied to production or used as templates, they could leak information. Fix: Ensure example files never contain real credentials, API keys, or PII; add examples/ to .gitignore; use realistic but fake data in examples; clearly document that examples are for testing only
• Medium · No SBOM or dependency transparency — Repository root. The codebase lacks Software Bill of Materials (SBOM) or comprehensive dependency documentation. This makes it difficult to identify affected components during vulnerability disclosures. Fix: Generate and maintain SBOM using tools like syft or cyclonedx, implement dependency scanning in CI/CD pipeline, document all direct and transitive dependencies, and establish a vulnerability tracking process
• Low · Incomplete security documentation — SECURITY.md. While SECURITY.md exists, the provided excerpt is truncated. The full disclosure guidelines, contact information for security reports, and patch timeline may be incomplete. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/higress-group/higress shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live higress-group/higress repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/higress-group/higress.

What it runs against: a local clone of higress-group/higress — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in higress-group/higress | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of higress-group/higress. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/higress-group/higress.git
#   cd higress
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of higress-group/higress and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "higress-group/higress(\\.git)?\\b" \\
  && ok "origin remote is higress-group/higress" \\
  || miss "origin remote is not higress-group/higress (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".claude/skills/higress-auto-router/SKILL.md" \\
  && ok ".claude/skills/higress-auto-router/SKILL.md" \\
  || miss "missing critical file: .claude/skills/higress-auto-router/SKILL.md"
test -f "api/extensions/v1alpha1/wasmplugin.proto" \\
  && ok "api/extensions/v1alpha1/wasmplugin.proto" \\
  || miss "missing critical file: api/extensions/v1alpha1/wasmplugin.proto"
test -f ".claude/skills/higress-wasm-go-plugin/SKILL.md" \\
  && ok ".claude/skills/higress-wasm-go-plugin/SKILL.md" \\
  || miss "missing critical file: .claude/skills/higress-wasm-go-plugin/SKILL.md"
test -f ".claude/skills/nginx-to-higress-migration/SKILL.md" \\
  && ok ".claude/skills/nginx-to-higress-migration/SKILL.md" \\
  || miss "missing critical file: .claude/skills/nginx-to-higress-migration/SKILL.md"
test -f ".claude/skills/higress-openclaw-integration/SKILL.md" \\
  && ok ".claude/skills/higress-openclaw-integration/SKILL.md" \\
  || miss "missing critical file: .claude/skills/higress-openclaw-integration/SKILL.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/higress-group/higress"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.