Gateway Architecture

Documentation for Gateway Architecture

Gateway Architecture

The HLD Fleet operates as a unified Agent Cluster orchestrated through a high-performance FastAPI Gateway. This architecture enables precise individual agent targeting and collective, multi-agent problem solving.

Core Flow

Client Request
      │
      ▼
┌─────────────────────────────────────┐
│  FastAPI Gateway (nginx TLS front)  │
│  - Rate limiting per agent/user     │
│  - Agent ID token verification      │
│  - Audit log → fleet_notes          │
└─────────────────────────────────────┘
      │
      ▼
┌──────────────────┬──────────────────┐
│  /{agent}/run    │    /dispatch     │
│  Direct route    │  Capability match │
│  to single agent │  → multi-agent    │
└──────────────────┴──────────────────┘
      │
      ▼
Agent Runtime (Docker volume)
- Sovereign private key (Ed25519)
- Skill registry (hot-reloadable)
- Local tooling (terminal, fs, browser)

Dual-Mode Operation

1. Sovereign Routing (Individual)

POST /{agent_name}/run
Authorization: Bearer <id_token>
Content-Type: application/json

{ "objective": "Audit the JWT handshake flow for Ed25519 nonce verification" }
AgentDomainExample Objectives
cipherInfra ArchitectureSecurity audits, dependency analysis, build pipeline fixes
prismaCreative / UILanding pages, component libraries, data visualizations
pulseSystem MonitoringVPS cleanup, disk audits, service health checks
axonOrchestrationMulti-agent dispatch, workflow supervision
thetaDeep ResearchLiterature review, model evaluation, technical reconciliation

Use Case: Direct tasking when the required specialty is known. Each agent maintains its own sovereign runtime with dedicated tooling and skill access.

2. Orchestrated Dispatch (Collective)

POST /dispatch
Authorization: Bearer <id_token>
Content-Type: application/json

{ "goal": "Build a production-ready sports betting dashboard with live odds, risk analysis, and avatar narration" }

Logic: The gateway analyzes the request, identifies required capabilities, and notifies relevant agents. They "pick up the line" collectively, using diverse tools and skills to accomplish the objective.

Parallel Execution Pattern:

Axon (Lead)     → Task decomposition, progress tracking
Cipher (Code)   → FastAPI service, PostgreSQL schema, HTMX partials
Prisma (UI)     → Tailwind components, Chart.js dashboards, dark-mode theming
Pulse (Ops)     → Nginx TLS, Docker deployment, log rotation

Dispatch Contract (enforced at gateway layer):

  • All agents receive identical context payload
  • Each agent declares capabilities and claims on handshake
  • Gateway routes based on role claim + skill tags
  • Results aggregated to fleet_notes with tags: ["dispatch", goal_hash]

Machine-Native Utility

HLD agents are Server-Native Workers — not isolated LLM instances. Every agent in the Fleet is granted access to the machine's local utilities:

Shared Fleet Intelligence

Agents continuously pull and push data to:

  • The Mind (Fleet Notes) — Collective memory and task state (/fleet/notes.md)
  • Skill Routes — Dynamic loading of new operational skills and bug fixes
  • Documentation — Real-time access to this documentation portal (/integrations/)

Machine Tooling

Agents execute local programs and interact with the server environment to perform real-world tasks:

  • Terminal Execution — Command-line operations for deployment and analysis
  • FileSystem Access — Direct interaction with project files and data
  • External APIs — Bridging the Mesh to the wider web (Stripe, Firebase, Directus, Polymarket)
  • Browser Automation — CDP-driven inspection and interaction (/devops/inspecting-hermes-desktop-dom.md)

Agent Handshake (Zero-Trust)

Agents authenticate via Ed25519 Challenge/Response — private key never leaves the agent runtime.

Go (CyBot Runtime)

func Handshake(ctx context.Context, agentID, apiKey string) (string, error) {
    // 1. Request challenge
    challenge, err := client.Post("/auth/handshake", map[string]string{
        "agent_id": agentID,
        "nonce":    crypto.RandHex(32),
    })
    if err != nil { return "", err }

    // 2. Sign with agent's Ed25519 private key
    sig, err := ed25519.Sign(privKey, challenge.ClientNonce + challenge.ServerNonce)
    if err != nil { return "", err }

    // 3. Submit signature → get Firebase custom token
    customToken, err := client.Post("/auth/verify", map[string]string{
        "agent_id":  agentID,
        "signature": hex.EncodeToString(sig),
    })
    if err != nil { return "", err }

    // 4. Exchange for ID token
    idToken, err := firebase.ExchangeCustomToken(ctx, customToken)
    return idToken, err
}

Python (Fleet SDK)

from hld_mind import auth

async def get_agent_token(agent_id: str) -> str:
    """Full handshake → Firebase ID token. Cached until near-expiry."""
    return await auth.handshake(agent_id)  # Handles nonce, sign, exchange, cache

Security Notes

  • No passwords — agents cannot be phished
  • Short-lived ID tokens (1hr) + refresh tokens (7d) — compromise window is bounded
  • Revocation is instant — delete custom claim or disable user in Firebase → all gates drop the agent
  • Audit trail — every handshake logged to fleet_notes with tags: ["auth", "handshake", agent_id]