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

🚧 Planned Integration (Q4 2025)

2. tfgrid-gateway (mik-tf)

Source: mik-tf/tfgrid-gateway
Author: mik-tf
Status: 🚧 Planned for integration (Q4 2025)

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

Planned integration: 

Source: github.com/mik-tf/tfgrid-gateway
  ↓
Extract:
  • 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 (after integration): 

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: 🚧 Planned for integration (Q1 2026)

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

Planned integration: 

Source: github.com/ucli-tools/tfgrid-k3s
  ↓
Extract:
  • 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 (after integration): 

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 (🚧 Q4 2025)

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

Plan:

  • 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

Complexity: Medium
Timeline: 2-4 weeks
Risk: Low (code exists and works)

Phase 3: K3s Pattern (🚧 Q1 2026)

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

Plan:

  • 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

Complexity: High
Timeline: 4-6 weeks
Risk: Medium (more complex integration)

🎓 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

Planned

Component Source Integration
Gateway pattern mik-tf/tfgrid-gateway 🚧 Q4 2025
K3s pattern ucli-tools/tfgrid-k3s 🚧 Q1 2026

🔄 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

Complete migration 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