Quickstart Automation Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
The Quickstart Automation Pipeline provides a single-call mechanism to configure and deploy a working proxy within the HX-ProxyGroup control plane. It orchestrates multiple ordered operations—such as subscription creation, node filtering, and listener setup—into a single atomic request to ensure a functional proxy state without requiring the client to discover the underlying resource dependency order.
This pipeline exists because reaching a working proxy state manually requires several ordered calls that are not inherently discoverable from standard individual resource endpoints. It serves as an entry point for both the UI and external agents to rapidly initialize the Data Plane.
Sources: internal/api/quickstart.go:10-15, scripts/verify-admin-catalog.ts:133-145
Architecture and Data Flow
The pipeline follows a strict modular boundary where the API handler receives structured JSON requests, validates them against size limits, and delegates execution to a specialized service. The system uses a QuickstartService interface to allow deployments to include or omit orchestration logic during compilation.
The flow ensures that any proxy list included in the request body is handled within the same size constraints as the standard subscription endpoint.
Sources: internal/api/quickstart.go:17-45, AGENTS.md:46-52
Endpoint Configuration
The Quickstart pipeline is exposed via a dedicated administrative path. It is integrated into the system's capability catalog, allowing agents to identify it as a primary capability for environment setup.
| Component | Identifier / Value | Description |
|---|---|---|
| Endpoint Path | /api/v1/quickstart | The public URI for initiating the automation pipeline. |
| HTTP Method | POST | Only creation requests are accepted via this endpoint. |
| Payload Limit | subscriptionBodyLimit | Matches the max size of the subscription endpoint to allow large node lists. |
| Catalog ID | quickstart.create | The unique identifier used in the capability catalog for agent discovery. |
Sources: internal/api/quickstart.go:13-16, scripts/verify-admin-catalog.ts:109-112
Request and Error Handling
The pipeline implements specific error mapping to differentiate between malformed requests and execution failures during resource creation.
Sources: internal/api/quickstart.go:34-58
Implementation Constraints
The Quickstart pipeline adheres to the project's core architectural rules:
- Atomic State Generation: Every change generates a complete candidate configuration for the data plane.
- Decoupled Logic: The pipeline orchestrates domain services but does not directly implement proxy protocols (which are handled by the Mihomo data plane).
- Validation First: The system must validate the candidate configuration before atomic publication to the data plane.
Sources: AGENTS.md:20-24, AGENTS.md:73-77, web/src/pages/routing-page.tsx:288-305
Conclusion
The Quickstart Automation Pipeline simplifies the deployment lifecycle of proxy services by abstracting complex resource dependencies. By providing a single quickstart.create capability, the system enables rapid initialization for users and automated agents while maintaining the strict modular boundaries and validation requirements of the HX-ProxyGroup architecture.