# 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.