Skip to content

tunnel-manager — Concept Overview

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

Description

Create SSH Tunnels to the operator's remote hosts and host as an MCP Server for Agentic AI!

Enterprise Readiness

All agents in the ecosystem inherit enterprise-grade infrastructure from scion-sdk:

Feature Status Source
JWT/OIDC Authentication ✅ Built-in scion-sdk[auth] — Authlib JWKS + API key middleware
OpenTelemetry Instrumentation ✅ Built-in scion-sdk[logfire] — OTLP export, FastAPI auto-instrumentation
HashiCorp Vault Integration ✅ Built-in scion-sdk[vault] — secret://, env://, vault:// URI schemes
Audit Logging ✅ Built-in Append-only compliance trail with 30+ action types (CONCEPT:AU-OS.governance.wasm-micro-agent-sandbox)
Token Usage Analytics ✅ Built-in 4-bucket tracking with budget alerting (CONCEPT:AU-OS.governance.wasm-micro-agent-sandbox)
Prompt Injection Defense ✅ Built-in 25+ pattern scanner + jailbreak taxonomy (CONCEPT:AU-OS.config.secrets-authentication)
Guardrail Engine ✅ Built-in Input/output interception with block/redact/warn (CONCEPT:AU-OS.governance.reactive-multi-axis-budget)
Action Execution Pipeline ✅ Built-in Token, cost, duration, and node transition limits Dry-run / commit / rollback phases (CONCEPT:AU-ORCH.adapter.kg-graph-materialization)
Resource Scheduling ✅ Built-in Priority queuing + preemption limits (CONCEPT:AU-OS.state.cognitive-scheduler-preemption)
Session Concurrency ✅ Built-in Enqueue/reject/interrupt/rollback (CONCEPT:AU-OS.governance.reactive-multi-axis-budget)

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 scion-sdk (inherited)

📖 Full Registry: See scion-sdk/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 run 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 use a Parallel SSH Sub-Agent Dispatch architecture:

  1. Async Connection Pools: Instead of linear loops, tunnel-manager uses asyncssh and asyncio.gather to run batches of 1,000 SSH connections concurrently.
  2. Dynamic Inventory Resolution: The target hosts can be dynamically queried from Cloud Providers (AWS/GCP tags) or existing CMDBs (ServiceNow), mapping smoothly into the Agent's Knowledge Graph.
  3. Payload MapReduce: Similar to the systems-manager daemon architecture, running cat /etc/os-release across 10,000 hosts will 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