ops-bridge/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

ops-bridge — Claude Code Instructions

Purpose: SSH reverse tunnel lifecycle manager. Keeps remote execution environments (COULOMBCORE, Railiance nodes) connected to the local Custodian State Hub so Claude Code sessions on those machines have full MCP connectivity.

Domain: custodian Repo slug: ops-bridge Repo ID: 1bf99f56-6e94-4379-a9ea-295a4c181889

Custodian State Hub Integration

State Hub: http://127.0.0.1:8000

Session Protocol

Step 1 — Orient

get_domain_summary("custodian")

Step 2 — Scan workplans

ls workplans/

During work: use record_decision(), add_progress_event(), resolve_decision().

Session close: add_progress_event() with workstream_id.

If workplan files were modified, run from ~/the-custodian/state-hub/:

make fix-consistency REPO=ops-bridge

Workplan Convention (ADR-001)

File location: workplans/BRIDGE-WP-NNNN-<slug>.md Prefix: BRIDGE-WP

What this repo builds

A CLI tool (bridge) that manages named SSH reverse tunnels:

bridge up [TUNNEL]      # start tunnel(s)
bridge down [TUNNEL]    # stop tunnel(s)
bridge restart [TUNNEL] # restart tunnel(s)
bridge status           # show all tunnels: state, uptime, last health check
bridge logs [TUNNEL]    # tail reconnect log

Config file: ~/.config/bridge/tunnels.yaml

Each tunnel:

• Named (e.g. state-hub-coulombcore)
• Reverse SSH port-forward: ssh -R remote_port:127.0.0.1:local_port host
• Auto-reconnects on drop (backoff loop)
• Optional HTTP health check to confirm the forwarded service is reachable

PRD: workplans/BRIDGE-WP-0001-initial-implementation.md

Stack

• Language: Python 3.11+
• CLI framework: Typer
• Dependencies: typer, pyyaml, httpx
• Packaging: uv tool install (single command install, no venv activation)
• No system daemons — process management is internal, PID tracked in ~/.local/state/bridge/

Dev Commands

# Install locally for development
uv tool install -e .

# Run tests
uv run pytest

# Run a single test
uv run pytest tests/test_tunnel.py::test_name -v

# Lint
uv run ruff check .

Architecture

OpsBridge has two logical components:

1. OpsBridge — tunnel lifecycle manager (this repo) Manages named SSH reverse tunnels defined in ~/.config/bridge/tunnels.yaml. Each tunnel runs in a subprocess with a reconnect backoff loop; PIDs are tracked in ~/.local/state/bridge/. Bridge states: stopped → starting → connected → degraded → failed. The degraded state means SSH is up but the optional HTTP health check is failing.

2. OpsCatalog — operations knowledge repository (planned extension) A Git-backed YAML catalog of operations domains, targets, bridges, and actor classes. OpsBridge consumes this catalog to resolve bridge identifiers and orient operators. Schema examples are in wiki/OpsCatalogSpecification.md. The catalog layout follows: opscatalog/domains/<domain>/{domain.yaml, targets/, bridges/, docs/}.

Key design constraints:

• OpsBridge owns lifecycle management only; it does not own identity/credentials
• Each tunnel is identified by name (e.g. state-hub-coulombcore); names used in config, CLI args, and log filenames must stay consistent
• Actor attribution (human operator vs. automation agent) is tracked per bridge for audit log traceability (FRS §5.7)

Specification docs are in wiki/: PRD (OpsBridgePrd.md), FRS (OpsBridgeFrs.md), and OpsCatalog spec (OpsCatalogSpecification.md).

Repo boundary

This repo owns tunnel lifecycle management only. It does not own:

• State hub code → the-custodian/state-hub/
• SSH key management → railiance-infra/ (S1) or user dotfiles
• Ansible/provisioning → railiance-infra/

Quick Reference

~/the-custodian/state-hub/mcp_server/TOOLS.md