Admin Web Surface

Relevant source files

The following files were used as context for generating this wiki page:

• src/admin/mod.rs
• src/admin/html.rs
• src/admin/codex.rs
• tests/admin_surface.rs
• ARCHITECTURE.md
• src/server.rs

The Admin Web Surface is an opt-in browser-based interface within the shunt gateway designed for account provisioning and monitoring the status of provider pools. It provides operators with a visual dashboard to manage multi-account configurations and view real-time pool health without requiring direct access to the gateway's underlying configuration files.

The surface is primarily used for ChatGPT/Codex account provisioning and read-only dashboarding of active accounts. Its existence is determined at startup based on the configuration, and it operates as a distinct sub-router within the main Axum server architecture.

Sources: ARCHITECTURE.md:46-52, ARCHITECTURE.md:144-146, docs/m9-admin-surface.md

System Architecture

The Admin Web Surface is integrated into the shunt-gateway through the admin module. It depends on the accounts, auth, and config modules to perform its functions. While the main proxy handles high-volume LLM traffic, the admin surface provides an out-of-band management layer.

The diagram shows the internal structure of the admin module and its relationship with core gateway components.
Sources: ARCHITECTURE.md:46-52, src/admin/mod.rs

Router and Endpoint Registration

The admin router is built conditionally during server initialization. If admin_auth is configured in the gateway settings, the server attaches the admin sub-routes to the main application router.

Endpoint	Method	Description
/	GET	Main dashboard view showing account pool status.
/login	GET/POST	Authentication for admin access.
/logout	POST	Terminates the admin session.
/codex/add	GET/POST	Interface for adding new ChatGPT/Codex accounts.
/codex/refresh	POST	Triggers manual token refresh for an account.

Sources: src/admin/mod.rs, tests/admin_surface.rs:15-30

Account Provisioning & Monitoring

One of the primary functions of the Admin Web Surface is the management of account pools, particularly for providers requiring complex authentication like ChatGPT/Codex.

Codex Account Integration

The codex.rs module handles the logic for adding and validating ChatGPT accounts via the web surface. This includes handling OAuth flows or session token entries required by the Codex adapter.

This flow illustrates the process of adding a new account through the web interface.
Sources: src/admin/codex.rs, src/admin/mod.rs

Dashboard Components

The dashboard, rendered via html.rs, provides a visual representation of the accounts.rs multi-account pool. Key metrics and statuses displayed include:

• Account ID/Email: Identifier for the account.
• Provider Status: Current health of the account connection (e.g., Active, Rate-limited, Token Expired).
• Usage Metrics: Basic request counters if metrics are enabled.
• Rotation Order: The current position or weight of the account within the load-balancing pool.

Sources: src/admin/html.rs, src/admin/mod.rs, ARCHITECTURE.md:46-52

Security and Authentication

Access to the Admin Web Surface is strictly controlled. It is not enabled by default and requires explicit configuration.

1. Inbound Authentication: The surface uses the [server.admin_auth] configuration. If this block is missing, the admin routes are not mounted, and the endpoints return 404.
2. Session Management: Once authenticated, a session is established to allow the operator to perform multiple actions without re-authenticating.
3. Read-Only vs. Write Access: While most of the dashboard is read-only (monitoring pools), specific provisioning endpoints like /codex/add require write access to the underlying credential files.

Sources: ARCHITECTURE.md:144-146, src/admin/mod.rs, tests/admin_surface.rs:40-60

Technical Implementation Notes

HTML Generation

The admin surface uses a server-side rendering approach located in src/admin/html.rs. This avoids the need for a complex frontend build pipeline and ensures the admin interface is lightweight and contained entirely within the Rust binary.

// Example of the structure used for rendering components in html.rs
pub fn render_dashboard(state: &AdminState, pools: &AccountPools) -> Html<String> {
    // Logic to iterate over pools and generate HTML tables
    // Sources: [src/admin/html.rs]
}

Sources: src/admin/html.rs

Multi-Account Synchronization

When an account is added or modified via the admin surface, the changes are propagated to the SharedState. Because shunt uses arc-swap for hot-reloading configuration, the admin surface can update the live account pool without requiring a full process restart.

Sources: ARCHITECTURE.md:144-146, src/admin/mod.rs

Summary

The Admin Web Surface provides a critical operational layer for shunt users, enabling visual management of account pools and simplifying the complex task of provisioning ChatGPT/Codex credentials. By integrating directly with the gateway's hot-reloadable state, it allows for dynamic adjustments to provider configurations with minimal disruption to in-flight LLM requests.