timmy-config/scripts

Gemini Sovereign Infrastructure Suite

This directory contains the core systems of the Gemini Sovereign Infrastructure, designed to systematize fleet operations, governance, and architectural integrity.

Principles

1. Systems, not Scripts: We build frameworks that solve classes of problems, not one-off fixes.
2. Sovereignty First: All tools are designed to run locally or on owned VPSes. No cloud dependencies.
3. Von Neumann as Code: Infrastructure should be self-replicating and automated.
4. Continuous Governance: Quality is enforced by code (linters, gates), not just checklists.

Tools

[OPS] Provisioning & Fleet Management

• provision_wizard.py: Automates the creation of a new Wizard node from zero.
  • Creates DigitalOcean droplet.
  • Installs and builds llama.cpp.
  • Downloads GGUF models.
  • Sets up systemd services and health checks.
• fleet_llama.py: Unified management of llama-server instances across the fleet.
  • status: Real-time health and model monitoring.
  • restart: Remote service restart via SSH.
  • swap: Hot-swapping GGUF models on remote nodes.
• skill_installer.py: Packages and deploys Hermes skills to remote wizards.
• model_eval.py: Benchmarks GGUF models for speed and quality before deployment.
• phase_tracker.py: Tracks the fleet's progress through the Paperclips-inspired evolution arc.
• cross_repo_test.py: Verifies the fleet works as a system by running tests across all core repositories.
• self_healing.py: Auto-detects and fixes common failures across the fleet.
• agent_dispatch.py: Unified framework for tasking agents across the fleet.
• telemetry.py: Operational visibility without cloud dependencies.
• gitea_webhook_handler.py: Handles real-time events from Gitea to coordinate fleet actions.

[ARCH] Governance & Architecture

• architecture_linter_v2.py: Automated enforcement of architectural boundaries.
  • Enforces sidecar boundaries (no sovereign code in hermes-agent).
  • Prevents hardcoded IPs and committed secrets.
  • Ensures SOUL.md and README.md standards.
• adr_manager.py: Streamlines the creation and tracking of Architecture Decision Records.
  • new: Scaffolds a new ADR from a template.
  • list: Provides a chronological view of architectural evolution.

Usage

Most tools require DIGITALOCEAN_TOKEN and SSH access to the fleet.

# Provision a new node
python3 scripts/provision_wizard.py --name fenrir --model qwen2.5-coder-7b

# Check fleet status
python3 scripts/fleet_llama.py status

# Audit architectural integrity
python3 scripts/architecture_linter_v2.py

Fleet Inventory Contract

The fleet inventory is defined in timmy-config/config.yaml under the fleet: key. All [OPS] scripts read this data at runtime, eliminating hard-coded IPs and paths.

fleet.inventory — Per-Host Definition

fleet:
  inventory:
    <hostname>:
      ip: <string>           # Public or private IP address
      port: <int>            # SSH target port (typically 22)
      role: <string>         # Logical role (hub, forge, agent-host, world-host)
      remote_root: <path>    # Remote root directory for Hermes operations
      capabilities: [...]    # Feature tags the host supports

Each host entry exposes: ip, port, role, remote_root, capabilities. The capabilities tag is freeform but standardized across the fleet (e.g., gateway, orchestrator, forge, agent-host, llm-host, world-host).

fleet.path_contracts — Path Abstractions

fleet:
  path_contracts:
    hermes_agent_local:  ../hermes-agent     # Path to local hermes-agent repo (relative to timmy-config)
    hermes_remote:       /opt/hermes         # Remote Hermes root on fleet nodes
    skills_remote:       /opt/hermes/skills  # Remote skills directory

All scripts reference paths via get_path_contract(key, default) or get_remote_root() helpers. This centralizes path management across local (mac) and remote wizards.

Override Mechanism

Set the TIMMY_CONFIG environment variable to point at an alternate config.yaml:

export TIMMY_CONFIG=/path/to/alternate/config.yaml
python3 scripts/fleet_llama.py status

Without TIMMY_CONFIG, scripts auto-resolve timmy-config/config.yaml relative to their scripts/ directory.

Fallback Defaults

If config.yaml is missing or the fleet: section is absent, scripts fall back to the canonical production fleet:

Hostname	IP	Role
mac	10.1.10.77	hub
ezra	143.198.27.163	forge
allegro	167.99.126.228	agent-host
bezalel	159.203.146.185	world-host

Fleet eviction occurs through config changes, not code edits.

---

Built by Gemini — The Builder, The Systematizer, The Force Multiplier.