INTENT

Purpose

This repository exists to provide a reliable, inspectable, and controllable connectivity layer between distributed dev, build, test and execution environments for dev and ops personal human and agentic.

Its role is to ensure that remote machines can consistently and safely “phone home” without requiring complex network infrastructure or manual intervention.

Primary Utility

The repository provides a managed SSH reverse tunneling system that:

Maintains continuous connectivity between remote systems and a central hub
Makes connectivity observable, auditable, and controllable
Exposes this capability as both a CLI tool and an MCP-accessible service

It transforms raw SSH port-forwarding into a first-class operational primitive.

Intended Users

Human operators (adm) managing infrastructure and connectivity
LLM-based agents (agt) requiring stable access to local services
Deterministic automations (atm) coordinating distributed workloads

Strategic Role in the System

This repository acts as the connectivity backbone of the custodian ecosystem:

It enables remote agents and services to participate in a locally anchored control plane
It decouples execution location from control location
It supports a hub-and-spoke topology where the Custodian State Hub remains central

Strategic Boundaries

This repository is not intended to:

Replace SSH as a general-purpose access mechanism
Act as a credential authority or security policy engine
Provide full network virtualization (e.g., VPN, mesh networking)
Host or orchestrate application workloads

Its responsibility ends at secure, observable, and managed connectivity via tunnels.

Design Principles

Continuity over convenience Connectivity must persist across failures without manual recovery
Observability as a first-class concern All lifecycle events must be traceable and attributable
Actor-aware operations Every action is tied to a clearly defined actor type (adm, agt, atm)
Pluggable security integration Works with both static keys and external certificate authorities without owning them
Toolability All capabilities should be accessible programmatically (MCP) and operationally (CLI)

Maturity Target

A mature version of this repository should:

Provide fully autonomous tunnel lifecycle management across heterogeneous environments
Integrate seamlessly with centralized access control and certificate systems
Serve as a standardized connectivity primitive across all Custodian-managed systems
Offer complete operational transparency for all connectivity-related actions
Be robust enough to act as the default connectivity layer for distributed agent systems

Stability Note

Changes to this file represent a deliberate shift in repository purpose or role within the system architecture.

Such changes should be rare and made with explicit intent.

3.0 KiB Raw Blame History