Skip to content

Source Repositories & Acknowledgments

TFGrid Compose was built by extracting and unifying proven, production-ready implementations.

🎯 Philosophy

TFGrid Compose is not built from scratch. Instead, it:

  1. Extracts working code from proven repositories
  2. Unifies them under a common deployer framework
  3. Simplifies the deployment experience
  4. Standardizes the workflow

This approach provides: - ✅ Battle-tested code - Already working in production - ✅ Faster development - No reinventing the wheel - ✅ Lower risk - Proven architectures - ✅ Quality assurance - Real-world validation

📦 Source Repositories

✅ Integrated (Current)

1. tfgrid-ai-agent (mik-tf)

Source: mik-tf/tfgrid-ai-agent
Author: mik-tf
Status: ✅ Fully integrated into TFGrid Compose (v1.0.0)

What it provides:

  • Complete AI coding agent deployment
  • Qwen AI integration
  • Project management system
  • Remote execution workflows
  • Git integration
  • Developer user provisioning

Integration: 

Source: github.com/mik-tf/tfgrid-ai-agent
  ↓
Extracted:
  • Infrastructure code → patterns/single-vm/infrastructure/
  • Platform config → patterns/single-vm/platform/
  • AI agent app → tfgrid-compose/tfgrid-ai-agent/
  ↓
Result: tfgrid-ai-agent deployable via tfgrid-compose

Changes made:

  • ✅ Extracted infrastructure as reusable pattern
  • ✅ Separated app from deployment logic
  • ✅ Created manifest system (tfgrid-compose.yaml)
  • ✅ Fixed project directory structure (Oct 8, 2025)
  • ✅ Unified CLI commands

Before (Standalone): 

cd tfgrid-ai-agent
make deploy
make login
make create project=my-app

After (TFGrid Compose): 

tfgrid-compose up
tfgrid-compose agent login
tfgrid-compose agent create

✅ Integrated

2. tfgrid-gateway (mik-tf)

Source: mik-tf/tfgrid-gateway
Author: mik-tf
Status: ✅ Integrated into TFGrid Compose

What it provides:

  • Public IPv4 gateway deployment
  • NAT-based gateway (nftables)
  • Proxy-based gateway (HAProxy + Nginx)
  • SSL/TLS automation (Let's Encrypt)
  • WireGuard + Mycelium networking
  • Network redundancy features
  • Live demo system with status pages
  • Port forwarding configuration
  • Path-based routing

Key features:

  • ✅ Dual gateway modes: NAT vs Proxy
  • ✅ SSL certificates: Free Let's Encrypt with auto-renewal
  • ✅ Network redundancy: WireGuard + Mycelium both mode
  • ✅ Flexible access: Port-based or path-based
  • ✅ Security features: Disable public port forwarding
  • ✅ Production-ready: Used in real deployments

Integration: 

Source: github.com/mik-tf/tfgrid-gateway
  ↓
Extracted:
  • Gateway infrastructure → patterns/gateway/infrastructure/
  • NAT/Proxy configs → patterns/gateway/platform/
  • SSL automation → patterns/gateway/ssl/
  • Network configs → patterns/gateway/networking/
  ↓
Result: Gateway pattern in tfgrid-compose

Usage: 

tfgrid-compose up my-webapp --pattern=gateway --domain=myapp.com

Repository stats:

  • 1,054 commits
  • Complete Terraform + Ansible implementation
  • Comprehensive documentation
  • Production deployments validated

3. tfgrid-k3s (ucli-tools)

Source: ucli-tools/tfgrid-k3s
Organization: ucli-tools
Status: ✅ Integrated into TFGrid Compose

What it provides:

  • Complete K3s cluster deployment
  • Multi-node orchestration (control + workers)
  • Management node with K9s TUI
  • MetalLB load balancer
  • Nginx Ingress controller
  • Dual-stack networking (IPv4/IPv6)
  • High availability support
  • Auto-scaling workers

Key features:

  • ✅ K3s lightweight Kubernetes - Production-grade
  • ✅ Management node: kubectl, K9s, Helm pre-installed
  • ✅ Load balancing: MetalLB with IPv4/IPv6 support
  • ✅ Ingress: Nginx Ingress controller
  • ✅ Networking: Flannel CNI + WireGuard + Mycelium
  • ✅ Scalability: Add nodes dynamically
  • ✅ Production-ready: Real cluster deployments

Integration: 

Source: github.com/ucli-tools/tfgrid-k3s
  ↓
Extracted:
  • Cluster infrastructure → patterns/k3s/infrastructure/
  • K3s playbooks → patterns/k3s/platform/
  • MetalLB/Ingress → patterns/k3s/components/
  • Management node → patterns/k3s/management/
  ↓
Result: K3s pattern in tfgrid-compose

Usage: 

tfgrid-compose up my-saas --pattern=k3s
tfgrid-compose kubectl get nodes
tfgrid-compose k9s

Repository stats:

  • 522 commits
  • Complete K3s automation
  • Comprehensive K9s integration
  • Production cluster deployments

🔗 ai-agent Framework (mik-tf)

Source: mik-tf/ai-agent
Author: mik-tf
Status: ✅ Dependency of tfgrid-ai-agent

What it provides:

  • AI coding loop technique
  • Qwen CLI integration
  • Project management framework
  • Continuous automation system

Inspiration: Based on the "Ralph" coding technique by Geoff Huntley, extended into a production-ready automation platform.

Usage: This framework is automatically installed on tfgrid-ai-agent VMs and provides the underlying AI automation capabilities.

🏗️ Extraction & Integration Process

Phase 1: Single-VM Pattern (✅ Complete)

Source: Infrastructure from mik-tf/tfgrid-ai-agent

Extraction: 1. ✅ Terraform configs extracted 2. ✅ Ansible playbooks generalized 3. ✅ WireGuard setup automated 4. ✅ Pattern metadata created 5. ✅ Documentation written

Result:

  • Reusable single-vm pattern
  • Works with any application
  • Clean separation of concerns

Phase 2: Gateway Pattern (✅ Complete)

Source: mik-tf/tfgrid-gateway (complete repo)

Completed:

  • Extract Terraform multi-VM configs
  • Extract Ansible NAT/proxy playbooks
  • Extract SSL automation (certbot)
  • Create gateway pattern structure
  • Adapt to manifest system
  • Test with multiple apps
  • Write pattern documentation

Phase 3: K3s Pattern (✅ Complete)

Source: ucli-tools/tfgrid-k3s (complete repo)

Completed:

  • Extract Terraform cluster configs
  • Extract Ansible K3s playbooks
  • Extract MetalLB/Ingress configs
  • Create k3s pattern structure
  • Add Helm chart support
  • GitOps integration
  • Write pattern documentation

🎓 What We Learned

From mik-tf/tfgrid-ai-agent

  • ✅ Clean deployment hooks - setup → configure → healthcheck
  • ✅ Developer user system - Non-root user provisioning
  • ✅ Remote execution - Run commands from local machine
  • ✅ Project organization - Structured workspace

From mik-tf/tfgrid-gateway

  • ✅ Dual gateway modes - NAT vs Proxy flexibility
  • ✅ SSL automation - Let's Encrypt integration
  • ✅ Network redundancy - Multiple network paths
  • ✅ Security controls - Granular access control

From ucli-tools/tfgrid-k3s

  • ✅ Management node pattern - Dedicated cluster control
  • ✅ Component integration - MetalLB + Ingress automation
  • ✅ Dual-stack networking - IPv4/IPv6 support
  • ✅ K9s TUI - Better cluster management UX

🙏 Acknowledgments

Individual Contributors

mik-tf

  • Created tfgrid-ai-agent (complete AI deployment)
  • Created tfgrid-gateway (gateway patterns, SSL, networking)
  • Created ai-agent framework (loop technique)
  • Provided foundation for TFGrid Compose

ucli-tools organization

  • Created tfgrid-k3s (complete K3s cluster deployment)
  • Advanced Kubernetes automation
  • Management node patterns

Geoff Huntley

  • Pioneered "Ralph" AI coding technique
  • Inspired ai-agent framework

ThreeFold Community

  • ThreeFold Grid infrastructure
  • Terraform provider
  • Community support

📊 Code Origin Breakdown

Current (v1.0.0)

Component Source Integration
Infrastructure mik-tf/tfgrid-ai-agent ✅ Extracted as pattern
Platform config mik-tf/tfgrid-ai-agent ✅ Generalized for reuse
AI agent app mik-tf/tfgrid-ai-agent ✅ Separated from deployer
CLI tool TFGrid Compose ✅ Built from scratch
Context files TFGrid Compose ✅ New feature
Agent subcommand TFGrid Compose ✅ New feature

All Patterns Integrated

Component Source Integration
Gateway pattern mik-tf/tfgrid-gateway ✅ Integrated
K3s pattern ucli-tools/tfgrid-k3s ✅ Integrated

🔄 Differences from Source

What's New in TFGrid Compose

Features not in source repos:

  • ✅ Universal deployer - Single CLI for all patterns
  • ✅ Manifest system - tfgrid-compose.yaml for apps
  • ✅ Context files - .tfgrid-compose.yaml for projects
  • ✅ Agent subcommand - Simplified AI agent operations
  • ✅ Pattern system - Reusable deployment strategies
  • ✅ State management - Track all deployments
  • ✅ Unified CLI - Consistent commands across patterns

Simplifications:

  • ✅ One command deployment (tfgrid-compose up)
  • ✅ Auto-detect configurations
  • ✅ Smart defaults
  • ✅ Better error messages
  • ✅ Idempotent operations

What's Preserved

Kept from source repos:

  • ✅ All core functionality
  • ✅ Infrastructure code (Terraform)
  • ✅ Platform configs (Ansible)
  • ✅ Network setup (WireGuard, Mycelium)
  • ✅ Best practices
  • ✅ Production readiness

📖 Migration Guides

From mik-tf/tfgrid-ai-agent

Before: 

git clone https://github.com/mik-tf/tfgrid-ai-agent
cd tfgrid-ai-agent
make deploy

After: 

git clone https://github.com/tfgrid-studio/tfgrid-compose
cd tfgrid-compose
make install
tfgrid-compose up ../tfgrid-ai-agent

Benefits:

  • ✅ Simpler commands
  • ✅ Context file support
  • ✅ Pattern reusability
  • ✅ Better documentation

Custom Apps Guide →

Source Repositories

TFGrid Compose Organization

📜 License & Attribution

Source Code Licenses

From source repos:

  • tfgrid-ai-agent: Apache 2.0 License
  • tfgrid-gateway: Apache 2.0 License
  • tfgrid-k3s: Apache 2.0 License

TFGrid Compose:

  • tfgrid-compose: Apache 2.0 License
  • tfgrid-ai-agent: Apache 2.0 License
  • Commercial repos: Business Source License / Proprietary

Attribution

All source repositories are properly credited in: - ✅ README files - ✅ Documentation - ✅ Code comments - ✅ This acknowledgment page

Thank you to all contributors who made TFGrid Compose possible! 🙏

View current status → • View planned features →

TFGrid Studio Ecosystem

Integrated tools and resources