Management Console - Pharos Documentation

While this site (iamrichardd.com/pharos/) provides static documentation and architectural guidance, the Pharos Console is the dynamic interface used for managing your infrastructure in real-time.

What is the Pharos Console?

The Pharos Console is the Agent-Native Control Plane of your lab. It serves as the primary Human/AI Interface, transforming the high-performance RFC 2378 engine into an actionable, resource-first command center. Rather than relying solely on the CLI, the Web Console provides a unified, real-time view of your inventory, node telemetry, and security configuration directly from your browser.

Key Features

WebMCP Gateway: A secure JSON-RPC 2.0 bridge for AI agents to interact with your lab resources.
Resource-First MDB: High-density inventory management with visual search and metadata “glance” blocks.
Identity Bonding: A “First-to-Claim” enrollment system for securing new nodes.
TUI/Web Hybrid: Access the full server dashboard from any browser.

AI Orchestration with WebMCP

Pharos is built for the Agent-Native era. The Console implements the Model Context Protocol (MCP) and WebMCP to allow LLMs to safely manage your lab as a first-class citizen.

How WebMCP Works

WebMCP acts as a secure bridge between your browser and an AI agent (like Gemini or Claude). Instead of the agent “scraping” the DOM, the Console exposes structured JSON-RPC tools via the /mcp endpoint.

Tool Discovery: When you ask an agent to “Query my lab for Proxmox nodes,” the agent discovers and calls the query_mdb tool.
Human-in-the-Loop (HitL): For destructive actions (like provision_node), the Console will trigger a browser-level confirmation modal. The agent cannot bypass your manual approval.
Scoped Access: The agent only sees the tools and data you have explicitly granted access to via your current session.

Available Tools

Tool	Description	HitL Required
`query_mdb`	Search machine and infrastructure records using RFC 2378 syntax.	No
`provision_node`	Adds a new machine record to the database.	Yes
`mcp.list_keys`	Lists all SSH public keys currently authorized for write access.	No
`mcp.provision_key`	Enrolls a new SSH public key into the security tier.	Yes

Storage Tiers & Transparency

Pharos maintains strict engineering integrity by distinguishing between Home Lab and Enterprise capabilities.

Enterprise LDAP (Read-Only)

The Enterprise Tier utilizes LDAP-backed storage for seamless integration with existing corporate directories. In its current implementation, the LDAP Tier is Read-Only. This design decision ensures that Pharos can serve as a high-performance proxy for your existing source of truth without requiring administrative write-access to your corporate directory.

Home Lab (Full CRUD)

The Home Lab Tier uses a file-level, restart-survivable storage engine. This tier supports full Create, Read, Update, and Delete (CRUD) operations, allowing you to manage your lab with zero external dependencies.

Deployment & Separation

To maintain high availability, we recommend keeping these two sites separate:

Documentation (This Site): Hosted on GitHub Pages or a CDN. Always available, even if your lab is offline.
Management (Pharos Console): Hosted inside your private network (e.g., in a Proxmox LXC). Provides the direct interface to your pharos-server.

Running the Console

The Web Console ships as its own container image, separate from pharos-server. It also requires its own PHAROS_TLS_CERT/PHAROS_TLS_KEY (mandatory HTTPS — it refuses to start without them) and needs PHAROS_HOST pointed at your running pharos-server, since the container can’t resolve it otherwise. Reuse the hub’s own TLS certificate at /etc/pharos/certs/pharos-server.crt/.key instead of generating a new one — this is the same cert file pharos-server itself uses, so if you’re managing a real certificate (e.g. Let’s Encrypt via an external renewal process), the console picks it up automatically with no separate sync path to maintain:

sudo podman run -d --name pharos-web \
  -p 3000:3000 \
  -v /etc/pharos/certs:/certs:ro,Z \
  -e PHAROS_TLS_CERT=/certs/pharos-server.crt \
  -e PHAROS_TLS_KEY=/certs/pharos-server.key \
  -e PHAROS_HOST=<your-pharos-server-ip-or-hostname> \
  ghcr.io/iamrichardd/pharos-console-web:latest

Access the dashboard at https://<your-server-ip>:3000. Run with sudo (or as a user in the pharos group) — pharos-server.key is only readable by root/pharos group. If your certificate renews (Let’s Encrypt or otherwise), restart this container (podman restart pharos-web) to pick up the new file — pharos-server itself reloads on SIGHUP (see the Server Setup docs), but the console container does not currently support a restart-free reload. Didn’t come up? Check podman logs pharos-web.

Version Self-Reporting & Drift Alerting

On startup, pharos-console-web automatically registers its self-reported version with pharos-server using an add command, re-sending heartbeats on a 60-minute interval.

Hostname Identification: Set PHAROS_CONSOLE_HOSTNAME to specify the node hostname in Pharos MDB. If unset, it falls back to os.hostname() with a startup warning.
Self-Reported Version: Set at container build time (PHAROS_CONSOLE_VERSION, tied to release tags via PHAROS_VERSION build arg) and displayed in the console UI footer.
Drift Monitoring: Operators or Terraform can set expected_version on the console machine record (mdb change hostname=<console-host> make expected_version=<tag>). pharos-server evaluates version against expected_version during health monitor cycles and fires an alert webhook/script on mismatch.