Network Overview - BlueFly Agent Platform

Last Updated: 2025-12-26
Status: Production
Scope: Complete network architecture, topology, and configuration

This is the single source of truth for network infrastructure.
For detailed component documentation, see the Infrastructure Control Center.

---

Executive Summary

The BlueFly Agent Platform uses Tailscale mesh networking to connect multiple Mac machines and infrastructure devices into a unified, secure network. This document covers the complete network topology, router configuration, Tailscale setup, Cloudflare Tunnel integration, and distributed computing capabilities.

Key Principles:

• Cloudflare Tunnel = Public ingress ONLY (GitLab webhooks, APIs)
• Tailscale = Private access ONLY (admin, travel, agents)
• These planes must NEVER be mixed.

---

Physical Network Topology

Internet
  
Spectrum Modem
   Ethernet  Deco X60 Mesh WiFi System
      WiFi devices (general network)
  
   Ethernet  GL-BE3600 Router (GL-iNet 7)
       SSID: BlueflySecure (computer/workstation network)
       SSID: Bluefly-Agents (agent network)
       Subnet: 192.168.8.0/24
       Tailscale IP: 100.116.110.123
       Dynamic DNS: https://xa1b1d2.glddns.com
       Devices on Bluefly-Agents network

---

Network Infrastructure Details

Spectrum Modem

• Primary internet connection
• Connected via Ethernet to both Deco X60 and GL-BE3600

Deco X60 Mesh WiFi

• Product: TP-Link Deco X60 | AX3000
• URL: https://www.tp-link.com/us/deco-mesh-wifi/product-family/deco-x60/
• Connection: Ethernet from Spectrum modem
• Purpose: General WiFi network for home/office devices

GL-BE3600 Router (GL-iNet 7)

• Product: GL.iNet GL-BE3600 (Slate 7)
• URL: https://www.gl-inet.com/products/gl-be3600/
• Connection: Ethernet from Spectrum modem
• Local IP: 192.168.8.1
• Tailscale IP: 100.116.110.123
• Device ID: xa1b1d2
• Dynamic DNS: https://xa1b1d2.glddns.com
• MAC: 94:83:C4:C1:B1:D2
• Hostname: gl-be3600
• Role: Subnet router for agent network
• Subnet Routing: Advertises 192.168.8.0/24 to Tailscale network

Network SSIDs

• BlueflySecure - Primary network (computer/workstation network)

  • WPA3 security
  • Client isolation: OFF
  • Admin access: Allowed
  • Tailscale: Enabled

• Bluefly-Agents - Agent network (dedicated agent infrastructure)

  • WPA3 security
  • Client isolation: OFF
  • Admin access: Allowed
  • Tailscale: Enabled
  • Subnet: 192.168.8.0/24

Detailed Router Configuration: See Router Documentation

---

Tailscale Network Configuration

Tailnet Information

• Tailnet: tailcf98b3.ts.net
• MagicDNS: Enabled
• Funnel: Available (but should be OFF on production devices)
• Zero Trust: WireGuard encryption
• Subnet Routing: 192.168.8.0/24 advertised

Tailscale Network Devices

Complete Device Inventory: See Network Inventory

Network Topology Visualization

1  100.108.129.7   - thomass-macbook-pro (macOS, exit node)
2  100.108.180.36  - thomass-macbook-pro-2 (macOS)
3  100.116.110.123 - gl-be3600 (linux)  Router
4  100.119.168.4   - default-agent-router (linux)
5  100.95.171.114  - tailscale-operator (linux)
6  100.67.125.25   - iphone (iOS)
7  100.120.242.98  - tscola'9720240422-qvvg4 (macOS)

Detailed Tailscale Configuration: See Tailscale Documentation

---

Cloudflare Tunnel (Public Ingress)

Tunnel Configuration

• Tunnel Name: agent-webhook
• Tunnel ID: f6da7bdf-d0f8-4796-a804-afb7984bbe11
• Status: Healthy (verified 2025-12-26)
• Running On: Mac M4 (100.108.129.7)
• Purpose: Public ingress for GitLab webhooks and NAS access

Published Application Routes

Note: GitLab webhook server runs on port 3001 (not 3000).

How Cloudflare Tunnel Works

GitLab SaaS
   HTTPS POST
Cloudflare DNS (api.blueflyagents.com)
  
Cloudflare Edge (TLS, WAF, DDoS protection)
   (OUTBOUND tunnel from Mac M4)
cloudflared (running on Mac M4)
  
http://localhost:3001 (GitLab Webhook Server)

Key Properties:

• cloudflared makes OUTBOUND connection to Cloudflare
• No inbound ports opened on network
• No router/NAT/port forwarding involved
• Domain never resolves to your public IP
• Works from anywhere (home, hotel, coffee shop, LTE, Starlink)

Detailed Cloudflare Configuration: See Cloudflare Documentation

---

OrbStack Kubernetes Networks

OrbStack creates multiple isolated networks for different purposes:

Ingress IP: 192.168.139.2
Domain Namespaces: .orb.local, .local.bluefly.io
Namespaces: 25 namespaces, 100+ deployments, 30+ running containers

---

Public Ingress vs Private Access (Critical Separation)

Bluefly Agent infrastructure uses two completely separate access planes:

Public Ingress (Cloudflare Tunnel)

Purpose: Accept inbound requests from external systems (GitLab webhooks, APIs)

Flow:

External Service (GitLab)
 Cloudflare DNS (api.blueflyagents.com)
 Cloudflare Edge
 Existing outbound Cloudflare Tunnel
 cloudflared (running on agent host)
 http://localhost:3001 (GitLab Webhook Server)

Key Properties:

• No inbound ports opened
• No router/NAT involvement
• Domain does NOT resolve to home IP
• Origin service binds to localhost only
• Cloudflare handles TLS, WAF, rate limits

Critical Configuration:

• Cloudflare Tunnel service URL: http://localhost:3001 (verified 2025-12-26)
• Never point Cloudflare at:
  • Tailscale hostnames
  • *.cfargotunnel.com URLs
  • LAN IPs
  • DDNS domains

Private Access (Tailscale)

Purpose: Secure access to home network and agents, travel connectivity via GL.iNet router

Flow:

Laptop / GL.iNet Router
 Tailscale Mesh
 Home subnet router
 Internal LAN services

Key Properties:

• Identity-based access (device + user)
• No public exposure
• No Cloudflare involvement
• No webhooks or public traffic

Explicit Rule: GitLab and other external systems must NEVER reach services through Tailscale.

---

Authoritative Architecture (Locked)

Last Updated: 2025-12-21
Status: LOCKED - Do not modify without explicit approval

This architecture is correct, modern, travel-safe, and zero-trust.

One-Page Ops Diagram (Reference Model)

If something doesn't match this, it's wrong.

                PUBLIC INGRESS (CONTROLLED)
================================================

GitLab SaaS
   |
   | HTTPS
   v
Cloudflare DNS (api.blueflyagents.com)
   |
Cloudflare Edge (WAF / TLS)
   |
Existing outbound tunnel
   |
cloudflared (runs on agent host)
   |
http://localhost:3001
   |
Agent / Webhook Service


                PRIVATE ACCESS (TAILSCALE)
================================================

Laptop / Phone
   |
Wi-Fi
   |
GL.iNet (Bluefly-Agent)
   |
Outbound TLS
   |
Tailscale Mesh
   |
Home Subnet Router
   |
Agents / LAN

Hard Boundary Rules

• Cloudflare never talks to Tailscale
• Tailscale never handles public traffic
• Routers never accept inbound connections
• DDNS never used

---

Tailscale Integration Points

1. @bluefly/agent-tailscale Package

Location: common_npm/agent_tailscale/

TypeScript package for Tailscale operations with distributed computing support.

Key Features:

• Simple API for Tailscale CLI operations
• Peer discovery and filtering based on OS, tags, and online status
• Network topology mapping
• Distributed computing resource discovery
• Latency-based node selection
• Integration with exo for distributed LLM inference

Repository: https://gitlab.com/blueflyio/agent-platform/agent_tailscale

Key Components:

• TailscaleClient: Wrapper for Tailscale CLI providing status, IP, up, down, and ping information
• TailscaleDiscovery: Peer discovery with filtering based on OS, tags, and online status
• TypeScript types: Full type safety

2. GitLab CI/CD Integration

Location: gitlab_components/templates/infrastructure/

GitLab CI Component for Secure Runner Access via Tailscale:

Features:

• Identity-based access with tags
• Works with managed runners
• Zero Trust security (WireGuard encryption)
• Ephemeral runner support
• Granular access control per repo/job

Usage:

include:
  - component: gitlab.com/llm/gitlab_components/infrastructure/tailscale-runner@<version>

variables:
  TAILSCALE_HOSTNAME: "gitlab-runner-${CI_PIPELINE_ID}"
  TAILSCALE_TAGS: "tag:ci-runner,tag:repo-${CI_PROJECT_NAME}"

3. Agent-BuildKit Services

Location: agent-buildkit/src/services/tailscale/

25+ Tailscale-related services including ACL management, API integration, auth keys, certificates, Cloudflare integration, DDEV integration, DNS management, Docker integration, Drupal integration, ephemeral devices, exit node management, funnel service, high availability, security hardening, JIT access, Kubernetes integration, device locking, monitoring, serve service, service discovery, split DNS, SSH access, subnet routing, webhook integration, and core service.

Detailed Tailscale Services: See Tailscale Documentation

---

Innovation: Distributed LLM Inference

Tailscale envisions a future where zero-configuration distributed LLM inference is seamlessly integrated into Tailscale mesh networks.

Key Innovations

1. Mesh-native Inference

   • Eliminates need for VPNs and port forwarding
   • Efficient and secure data transmission across network
   • Native inference experience

2. Smart Shard Placement Algorithm

   • Optimizes shard placement
   • 30-50% faster inference speed
   • Intelligent workload distribution

3. Elastic Clusters

   • Nodes can join or leave dynamically
   • Optimal resource utilization
   • Automatic scaling

4. Latency-optimized Routing

   • 3x faster response times
   • Minimizes latency
   • Efficient routing system

5. Hybrid CPU/GPU Inference with Automatic Fallback

   • Combines CPU and GPU power
   • Automatic fallback to GPU when necessary
   • Consistent performance

Use Cases

• Home lab + cloud hybrid
• Multi-office deployment
• Research collaboration across institutions

---

Preflight Regression Check

Run this checklist before debugging anything. Answer YES to all:

• api.blueflyagents.com resolves to Cloudflare (not home IP)
• Cloudflare Tunnel service URL = http://localhost:3001 (verified 2025-12-26)
• No port forwards exist on any router
• Tailscale Funnel disabled everywhere ( Currently enabled on Mac M4 and M3 - needs fixing)
• GL.iNet exit node OFF
• Laptop internet IP = hotel/LTE IP (not home IP)
• Home LAN reachable over Tailscale
• Public ingress works even if home IP changes

Mental Model Check: "If my public IP changed every 30 seconds, would this still work?"

• If NO something is misconfigured
• If YES architecture is correct

---

Tailscale CLI Quick Reference

# Network status
tailscale status

# Test connectivity
tailscale ping 100.116.110.123  # Test router connectivity

# Expose services (use sparingly - prefer Cloudflare Tunnel for public)
tailscale funnel 3006         # Expose agent-router
tailscale funnel 3003         # Expose agent-mesh
tailscale funnel 4000         # Expose LLM Gateway

# Network management
tailscale up --advertise-routes=192.168.8.0/24  # Advertise BlueflyMesh subnet

---

Current Issues (2025-12-26)

Critical Issues Requiring Action

1. Funnel Enabled on Production Devices

   • Devices: Mac M4 (100.108.129.7), Mac M3 (100.108.180.36)
   • Action: Disable Funnel on both devices via Tailscale admin
   • Impact: Security risk (Funnel should be OFF for webhook security)

2. Unapproved Subnet Route

   • Device: Mac M3 (100.108.180.36)
   • Route: 192.168.138.0/23
   • Action: Approve route in Tailscale admin or remove advertisement

3. Test-NET Routes in Production

   • Device: Mac M3 (100.108.180.36)
   • Routes: 192.0.2.0/24, 198.51.100.0/24 (TEST-NET addresses)
   • Action: Remove if not needed (RFC 5737 - should not be used in production)

4. Duplicate Router Device

   • Device: gl-be3600-1 (100.115.120.50) - never seen
   • Action: Verify if needed, remove if duplicate

Complete Issue List: See Network Inventory - Critical Issues

---

Summary

The BlueFly Agent Platform network infrastructure includes:

1. Network Infrastructure: Router setup with subnet routing
2. Tailscale Mesh: Secure private access (tailcf98b3.ts.net)
3. Cloudflare Tunnel: Public ingress for GitLab webhooks and NAS
4. CI/CD Pipelines: Secure GitLab runner access via Tailscale
5. Distributed Computing: LLM inference orchestration
6. Service Discovery: Agent mesh, knowledge graphs
7. Security: ACLs, JIT access, hardening
8. Platform Integrations: Kubernetes, Docker, Drupal, DDEV

For detailed component documentation, see:

• Infrastructure Control Center
• Network Inventory
• Tailscale Documentation
• Cloudflare Documentation
• Router Documentation
• Synology NAS Documentation

---

Related Documentation

• Infrastructure Control Center - Main infrastructure hub
• Network Inventory - Complete device and service inventory
• Architecture Documentation
• Development Workflow & CI/CD

---

This document is the single source of truth for network architecture. All network configuration should reference this document.