Why ArchRouter Exists

Running Hermes Agent and 9Router together creates an operational layer that is easy to overlook. The agent needs a reliable model route, providers need to be configured safely, updates need verification, and failures need enough context to diagnose without opening a dashboard or editing internal state by hand.

ArchRouter brings those responsibilities into one headless control layer. It provides a recovery-oriented CLI, a small read-only MCP surface, and Hermes gateway commands for inspecting and managing a local 9Router installation. Telegram is the first interactive gateway integration, but neither the core nor the CLI depends on Telegram.

The project is intentionally not an inference proxy. It manages the infrastructure around inference while leaving model traffic on its existing path.

Management: Hermes or CLI -> ArchRouter -> 9Router
Inference:  Hermes Agent -> 9Router -> Selected provider

That separation gives ArchRouter a narrow responsibility: operate the routing environment without carrying prompts, completions, or provider traffic itself.

Architecture

The core is interface-independent and talks to 9Router through a RouterAdapter boundary. The current NineRouterAdapter contains the upstream-specific behavior, while the CLI, MCP server, and Hermes integration call the same core services. This keeps management logic from becoming tied to one chat platform or one presentation layer.

CLI / Hermes commands / MCP / future interfaces
                         |
                   ArchRouter core
                         |
                    RouterAdapter
                         |
                 NineRouterAdapter
                         |
                      9Router

This boundary also matters because the 9Router management routes used by the official dashboard are not currently a documented, versioned public API. Keeping that dependency inside one adapter makes compatibility work more contained.

What It Can Operate

ArchRouter groups its current functionality around diagnostics, providers, models, and lifecycle management:

  • Detect Hermes Agent and 9Router installations and report their operational state.
  • Run doctor checks across runtimes, configuration permissions, gateway state, plugin and MCP registration, listener safety, service persistence, API reachability, and update sources.
  • Validate OpenAI-compatible and Anthropic-compatible provider endpoints before persistence.
  • Create, list, test, and remove custom providers through 9Router's management interface.
  • Assemble provider-scoped routable model catalogs from active 9Router connections and runtime model data.
  • Check update sources without installing anything.
  • Explicitly update npm-based 9Router installations and invoke the official Hermes updater with preflight and post-update verification.
  • Expose five non-destructive MCP tools for status, updates, providers, provider testing, and model discovery.

The CLI supports human-readable output and JSON for documented inspection commands, allowing the same core to work for an operator at a terminal and for controlled automation.

Hermes and Telegram Workflows

The Hermes plugin adds status, provider, update, provider-creation, and model-selection commands to the existing gateway. It does not create another Telegram bot or polling process. Authorization remains attached to the Hermes gateway allowlist.

The /newprovider workflow is deliberately stateful. It keeps short-lived conversation state in memory, deletes the Telegram message containing a provider credential before using it, and fails closed when deletion cannot be confirmed. After validation, it discovers the provider's model catalog and asks the operator to select a model explicitly.

The /archrouter model picker reads the currently routable provider and model catalog, verifies the callback against fresh state, then uses Hermes's built-in model-switch path. A successful selection proves that the route exists and Hermes accepted the configuration. It does not claim that a later inference request will succeed, because protected 9Router deployments may also require a separate runtime client key.

Security Boundaries

ArchRouter is built for a trusted Linux administrator, but it still narrows the authority of each interface:

  • The optional systemd service binds 9Router to 127.0.0.1:20128 instead of exposing its management port broadly.
  • Provider credentials enter through a hidden prompt, a named environment variable, or the deletion-gated Telegram flow.
  • ArchRouter does not store provider keys in its YAML configuration or return them from provider listings. 9Router owns persisted provider credentials.
  • Redirects are disabled for provider validation, operations are bounded by time and response size, and private, reserved, metadata, and link-local destinations are denied by default.
  • Diagnostic text and structured output are redacted before truncation or logging.
  • Management subprocesses use fixed argument vectors rather than a shell.
  • Provider mutation is intentionally absent from MCP.

These controls reduce accidental exposure and unnecessary authority. They do not replace network isolation, restrictive egress, credential rotation, or an administrator's review of high-impact operations.

Installation and First Commands

ArchRouter requires Linux, Python 3.11 or newer, uv, and Git. The tested platform for version 0.2.0 is Ubuntu 24.04 on x86_64.

git clone https://github.com/aldevvv/archrouter.git
cd archrouter
./install.sh

The installer creates a non-editable uv tool installation, writes a protected configuration file, backs up existing Hermes integration files, registers the plugin and MCP server when Hermes is present, and finishes by running diagnostics.

To install a localhost-only 9Router systemd user service as part of the same flow:

./install.sh --install-9router

Without that flag, ArchRouter does not install, replace, or reconfigure 9Router. Useful first commands are:

archrouter status
archrouter doctor
archrouter update check
archrouter provider list

Technology and Quality Gates

ArchRouter is a Python 3.11+ package built with Hatchling. Typer powers the CLI, httpx handles bounded HTTP operations, Pydantic and PyYAML model configuration, packaging handles versions, and the Python MCP package provides the stdio server.

The development workflow includes Ruff formatting and linting, strict mypy, pytest, package builds, and full-history secret scanning in CI. The documented version 0.2 quality run completed with 68 tests passing and one opt-in real-service test skipped.

Current Status

ArchRouter 0.2.0 is functional but intentionally honest about its experimental boundaries. Its 9Router management integration depends on dashboard-internal routes. Hermes adapter behavior can change between releases. Docker and source installations can be detected but are not updated automatically, and conversation state is lost when the gateway restarts.

The protected 9Router inference path also has a known gap: ArchRouter can persist a provider and switch Hermes to a routable model, but it does not yet provision the separate 9Router runtime client key into Hermes. Selection and successful inference remain two distinct checks.

The roadmap focuses on version-gated upstream compatibility, safer Docker and source updates, a supported Hermes callback interface, and a localhost-authenticated REST surface after the core management path stabilizes.

Sources

  1. ArchRouter README and architecture
  2. Router adapter boundary
  3. 9Router adapter implementation
  4. MCP server implementation
  5. Security policy
  6. Python package configuration