Admin Capabilities & API Definitions
Relevant source files
The following files were used as context for generating this wiki page:
The Admin Capabilities and API Definitions establish the management interface for the HX-ProxyGroup control plane. This system enables administrators and automated agents to configure subscriptions, manage proxy groups, and monitor data plane status through a structured REST API. The API is session-authenticated and primarily binds to loopback addresses by default to ensure security.
Sources: internal/api/server.go:420-430, AGENTS.md:100-105
API Architecture and Governance
The API follows a strict layered architecture: api -> application service -> domain/interface -> repository/dataplane. This structure ensures that handlers do not execute raw SQL and DTOs remain separate from database entities. A machine-readable capability catalog publishes every management endpoint, field name, and enum value to assist integration without requiring direct source code analysis.
Sources: AGENTS.md:40-48, internal/api/server.go:454-460
Request Flow and Security
Every request passes through a middleware stack that handles request ID generation, security headers, and authentication.
The diagram shows the sequence of middleware execution before a request reaches the core application logic.
Sources: internal/api/server.go:410-418, internal/api/server.go:580-590
Core Administrative Endpoints
The API is organized into functional groups covering system status, node management, and proxy configuration.
System and Metadata
System endpoints provide information about the application version, repository, and operational status of the Mihomo data plane.
| Endpoint | Method | Description |
|---|---|---|
/health/live | GET | Basic liveness check. |
/health/ready | GET | Readiness check verifying internal services are initialized. |
/api/v1/system/info | GET | Returns application version and supported protocols. |
/api/v1/system/resources | GET | Returns host CPU and memory utilization. |
Sources: internal/api/server.go:421-423, internal/api/server.go:478-485, internal/api/server.go:520-532
Node Management
The Node API handles the lifecycle of proxy nodes, including health checks and state management. Nodes can exist in several states: candidate, healthy, degraded, quarantined, disabled, or retired.
This sequence illustrates the process of triggering batch health checks for specific proxy nodes.
Sources: internal/api/nodes.go:12-28, internal/store/migrations.go:56-61
Data Plane Control
The data plane interface manages the Mihomo process and its configuration.
- Apply Configuration: Recompiles the desired state and applies it to the data plane.
- Status Monitoring: Tracks PID, version, and the number of active listeners.
Sources: internal/api/server.go:474-477, internal/store/migrations.go:104-118
Database Schema and Persistence
The system uses SQLite with a structured migration system to maintain the desired state. The schema is strict, utilizing CHECK constraints and STRICT table definitions.
Key Management Tables
| Table | Key Fields | Purpose |
|---|---|---|
subscriptions | id, source_type, enabled | Tracks external node sources. |
nodes | id, fingerprint, lifecycle_state | Stores canonical proxy configurations. |
proxy_groups | id, strategy, source_spec_json | Defines node selection and load balancing. |
listeners | id, bind_address, port, kind | Manages entry points (Mixed, HTTP, VLESS, etc). |
Sources: internal/store/migrations.go:20-100
Automation and Agent Integration
For automated management, the project provides specific tools and constraints:
- Capability Catalog: A dedicated endpoint at
CapabilityCatalogPaththat publishes the full API contract. - API Keys: Persistent tokens managed via
/api/v1/terminal/api-keysfor non-session-based access. - Verification Scripts: The
verify-admin-catalog.tsscript ensures the Go server, the documentation, and agent skills remain synchronized.
Sources: scripts/verify-admin-catalog.ts:15-30, internal/api/server.go:454-460, internal/store/migrations.go:610-618
Conclusion
The Admin Capabilities and API Definitions provide a robust, versioned interface for controlling the HX-ProxyGroup environment. By separating the control plane from the data plane and enforcing strict architectural boundaries, the system ensures reliable proxy management suitable for both human administrators and AI agents.