tunnel-manager — Concept Overview¶

Category: Infrastructure | Ecosystem Role: MCP Server + A2A Agent Built on agent-utilities — the unified AGI Harness.

Description¶

Create SSH Tunnels to your remote hosts and host as an MCP Server for Agentic AI!

Enterprise Readiness¶

All agents in the ecosystem inherit enterprise-grade infrastructure from agent-utilities:

Feature	Status	Source
JWT/OIDC Authentication	✅ Built-in	`agent-utilities[auth]` — Authlib JWKS + API key middleware
OpenTelemetry Instrumentation	✅ Built-in	`agent-utilities[logfire]` — OTLP export, FastAPI auto-instrumentation
HashiCorp Vault Integration	✅ Built-in	`agent-utilities[vault]` — `secret://`, `env://`, `vault://` URI schemes
Audit Logging	✅ Built-in	Append-only compliance trail with 30+ action types (CONCEPT:OS-5.4)
Token Usage Analytics	✅ Built-in	4-bucket tracking with budget alerting (CONCEPT:OS-5.4)
Prompt Injection Defense	✅ Built-in	25+ pattern scanner + jailbreak taxonomy (CONCEPT:OS-5.1)
Guardrail Engine	✅ Built-in	Input/output interception with block/redact/warn (CONCEPT:OS-5.3)
Action Execution Pipeline	✅ Built-in	Token, cost, duration, and node transition limits Dry-run / commit / rollback phases (CONCEPT:ORCH-1.4)
Resource Scheduling	✅ Built-in	Priority queuing + preemption limits (CONCEPT:OS-5.2)
Session Concurrency	✅ Built-in	Enqueue/reject/interrupt/rollback (CONCEPT:OS-5.3)

Concept Registry¶

This project implements or inherits the following ecosystem concepts:

Concept ID	Description	Source
TUN-1.0	Distributed SSH/RM Swarm	`tunnel-manager`
ECO-4.1	MCP & Universal Skills	`agent-utilities` (inherited)

📖 Full Registry: See agent-utilities/docs/overview.md for the complete 5-Pillar concept index.

Architecture¶

The tunnel-manager functions as the "Agentless Execution Arm" for the Agent OS Kernel. When an agent needs to execute commands or send/receive files across multiple remote systems without deploying persistent daemons, tunnel-manager bridges the gap.

TUN-1.0: Distributed SSH Swarm Scaling¶

To scale remote execution to 10,000+ hosts over SSH without facing catastrophic O(N) latency bottlenecks, tunnel-manager utilizes a Parallel SSH Sub-Agent Dispatch architecture:

Async Connection Pools: Instead of linear loops, tunnel-manager uses asyncssh and asyncio.gather to execute batches of 1,000 SSH connections concurrently.
Dynamic Inventory Resolution: The target hosts can be dynamically queried from Cloud Providers (AWS/GCP tags) or existing CMDBs (ServiceNow), mapping seamlessly into the Agent's Knowledge Graph.
Payload MapReduce: Similar to the systems-manager daemon architecture, running cat /etc/os-release across 10,000 hosts would overflow the LLM's context. The tunnel-manager MCP intercepts the 10,000 standard output strings and reduces them into a unified summary payload (e.g., "9,500 hosts are Ubuntu 24.04, 500 hosts are RHEL 9") before returning to the Agent.

This design guarantees that tunnel-manager remains purely agentless and strictly SSH-based, while achieving enterprise-grade horizontal scaling capabilities.

This project follows the standardized agent-package pattern:

tunnel-manager/
├── tunnel_manager/        # Source code
│   ├── __init__.py
│   ├── agent_server.py      # Entry point (create_graph_agent_server)
│   ├── api_client.py        # REST/GraphQL API wrapper
│   └── mcp_server.py        # FastMCP tool definitions
├── tests/                   # Test suite
├── docs/                    # Documentation
├── pyproject.toml           # Package metadata
├── mcp_config.json          # MCP server configuration
├── main_agent.json          # Agent identity & system prompt
└── Dockerfile               # Container deployment

MCP Configuration¶

stdio Mode¶

{
  "mcpServers": {
    "tunnel-manager": {
      "command": "uv",
      "args": ["run", "--with", "tunnel-manager", "tunnel-mcp"],
      "env": {}
    }
  }
}

Streamable HTTP Mode¶

tunnel-mcp --transport streamable-http --port 8001