@rubys/fly-explorer

Fly.io Explorer

A comprehensive web-based dashboard for managing Fly.io infrastructure using Model Context Protocol (MCP) integration with flyctl. Provides a complete graphical interface for all Fly.io operations without requiring command-line usage.

🚀 Features

Organization & Application Management

• Multi-Organization Support: Switch between organizations and view detailed statistics
• Complete App Lifecycle: Create, delete, and move applications between organizations
• Application Monitoring: Real-time status tracking (deployed, suspended, failed)
• Deployment Management: Deploy applications and track release history

Virtual Machine Management

• Machine Creation: Advanced machine creation with platform-aware configuration:
  • Regional deployment with automatic region/VM size population
  • Docker image specification
  • Environment variable management
  • Service/port configuration
  • Volume attachment
• Machine Operations: Complete lifecycle control:
  • Start/Stop/Restart machines
  • Clone machines with optional region changes
  • Cordon/Uncordon for allocation management
  • Destroy machines with force options
• Detailed Monitoring: Comprehensive machine information including hardware specs, network details, event logs, and health checks

Network & IP Address Management

• Complete IP Management: Comprehensive IP address allocation and management:
  • Allocate shared or dedicated IPv4 addresses
  • Allocate public IPv6 addresses
  • Allocate private IPv6 addresses for internal networking
  • Regional IP allocation with dropdown selection
  • View all assigned IP addresses (public and private) in organized table
  • Release public IP addresses when no longer needed
• Network Configuration: Custom network specification for advanced setups

Storage & Configuration Management

• Volume Management: Create, extend, delete, and monitor persistent volumes
• Secrets Management: Secure environment variable handling with deployment tracking
• SSL Certificate Monitoring: View certificate status, expiration, and validity

Real-time Monitoring & Logging

• Live Log Streaming: Real-time application logs with advanced filtering:
  • Filter by machine, region, or line count
  • Color-coded log levels (error, warn, info, debug)
  • ANSI escape sequence support for formatted output
  • Progress Indicators: Real-time progress notifications during log fetching
  • Auto-scroll: Automatically scrolls to show new messages as they arrive
  • Auto-retry: Automatically retries on timeout and resets the log window
• Extended Timeout Support: 24-hour timeout for long-running log operations
• Machine State Tracking: Live updates of machine status and events
• Platform Status: Monitor Fly.io platform health and available regions

Advanced Administration (MCP Tool Explorer)

• Universal Tool Access: Execute any flyctl command through an intuitive interface
• Dynamic Form Generation: Automatically generates forms based on tool schemas
• Parameter Validation: Type checking and required field validation
• Raw MCP Access: Direct access to all 54+ flyctl MCP tools for advanced operations

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  React Frontend │    │  Express Server │    │   flyctl MCP    │
│   (Port 3000)   │◄──►│   (Port 3001)   │◄──►│     Server      │
│                 │    │                 │    │                 │
│ • UI Components │    │ • REST API      │    │ • Tool Execution│
│ • State Mgmt    │    │ • MCP Client    │    │ • Data Parsing  │
│ • Real-time UI  │    │ • Data Transform│    │ • flyctl Bridge │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Technology Stack

• Frontend: React with TypeScript, responsive CSS design
• Backend: Express.js with comprehensive error handling
• MCP Integration: Full Model Context Protocol client implementation
• Real-time Updates: Automatic refresh and live status monitoring

📦 Installation

Quick Start with npx (Recommended)

Run instantly without installation:

npx @rubys/fly-explorer

This will download and start Fly Explorer automatically. Your browser will open automatically to http://localhost:3001

Global Installation

Install globally via npm to use the fly-explorer command anywhere:

npm install -g @rubys/fly-explorer
fly-explorer

Local Installation

Install in your project directory:

npm install @rubys/fly-explorer
npx fly-explorer

Prerequisites

• Node.js (v18+)
• flyctl binary available in system PATH (install flyctl)

Environment Variables

• NO_BROWSER=true - Disable automatic browser opening on startup

🚦 Development Setup

Quick Start

• Clone the repository:

git clone https://github.com/rubys/fly-explorer.git
cd fly-explorer

• Install dependencies:

npm install

• Ensure flyctl is available:

flyctl version

• Start development environment:

npm run dev

This starts:

• Frontend: http://localhost:5173 (React with Vite)
• Backend: http://localhost:3001 (Express API server)
• MCP Connection: Automatic connection to flyctl MCP server

Production Build

npm run build  # Build React frontend and server
npm start      # Start production server

📡 API Reference

Organization Management

• GET /api/organizations - List all organizations
• GET /api/organizations/:org - Get organization details
• POST /api/organizations/:org/apps - Create new application

Application Management

• GET /api/organizations/:org/apps - List applications
• DELETE /api/apps/:app - Delete application
• PUT /api/apps/:app/move - Move app between organizations
• POST /api/apps/:app/deploy - Deploy application
• GET /api/apps/:app/status - Get application status
• GET /api/apps/:app/releases - Get release history

Machine Management

• GET /api/apps/:app/machines - List machines
• GET /api/apps/:app/machines/:id - Get machine details
• POST /api/apps/:app/machines - Create machine
• DELETE /api/apps/:app/machines/:id - Destroy machine
• POST /api/apps/:app/machines/:id/start - Start machine
• POST /api/apps/:app/machines/:id/stop - Stop machine
• POST /api/apps/:app/machines/:id/restart - Restart machine
• POST /api/apps/:app/machines/:id/clone - Clone machine
• POST /api/apps/:app/machines/:id/cordon - Cordon machine
• POST /api/apps/:app/machines/:id/uncordon - Uncordon machine

IP Address Management

• POST /api/tools/fly-ips-list/execute - List all IP addresses (public)
• POST /api/tools/fly-ips-private/execute - List private IP addresses
• POST /api/tools/fly-ips-allocate-v4/execute - Allocate IPv4 address (shared/dedicated)
• POST /api/tools/fly-ips-allocate-v6/execute - Allocate public IPv6 address
• POST /api/tools/fly-ips-private/execute - Allocate private IPv6 address
• POST /api/tools/fly-ips-release/execute - Release IP addresses

Storage & Configuration

• GET /api/apps/:app/volumes - List volumes
• POST /api/apps/:app/volumes - Create volume
• DELETE /api/apps/:app/volumes/:id - Delete volume
• PUT /api/apps/:app/volumes/:id/extend - Extend volume
• GET /api/apps/:app/secrets - List secrets
• POST /api/apps/:app/secrets - Create/update secrets
• DELETE /api/apps/:app/secrets/:name - Delete secret
• GET /api/apps/:app/certificates - List SSL certificates

Platform Information

• GET /api/platform/regions - List available regions
• GET /api/platform/vm-sizes - List VM sizes and pricing
• GET /api/platform/status - Platform health status

Monitoring & Logs

• GET /api/apps/:app/logs - Stream application logs
• GET /api/tools - List all available MCP tools
• POST /api/tools/:tool/execute - Execute any MCP tool

🎯 Use Cases

Development Teams

• Rapid Prototyping: Quickly spin up applications and machines for testing
• Environment Management: Manage development, staging, and production environments
• Log Debugging: Real-time log monitoring with advanced filtering
• Resource Optimization: Monitor and adjust machine sizes and regional deployment

DevOps & Infrastructure

• Infrastructure as Code: Programmatic machine, volume, and IP management
• Multi-Organization Management: Handle multiple clients or projects
• Network Management: IP allocation and regional networking configuration
• Operational Monitoring: Track application health and performance
• Disaster Recovery: Machine cloning and cross-region deployment

Learning & Exploration

• Fly.io Onboarding: Visual introduction to Fly.io concepts and capabilities
• Command Discovery: Explore flyctl functionality through the MCP Tool Explorer
• Safe Experimentation: GUI-based operations with confirmation prompts

🔧 Advanced Features

MCP Tool Explorer

Access to all flyctl capabilities through a visual interface:

• Execute any of the 54+ available flyctl tools
• Dynamic parameter forms with validation
• Raw access to advanced operations not available in the main UI

Platform Integration

• Real-time Data: Live synchronization with Fly.io APIs
• Intelligent Parsing: Automatic handling of various flyctl output formats
• Error Handling: Comprehensive error messages and recovery suggestions

Safety Features

• Confirmation Dialogs: Protection against accidental destructive operations
• Validation: Input validation and type checking throughout
• Rollback Information: Clear indication of irreversible operations

🤝 Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature-name
• Make your changes and test thoroughly
• Submit a pull request with a clear description

Publishing (Maintainers Only)

To publish a new version to npm:

• Update version in package.json:

npm version patch  # or minor/major

• Build and publish:

npm run build
npm publish

• Push changes and tags:

git push origin main --tags

The package is published as @rubys/fly-explorer on npm.

📄 License

MIT License - see LICENSE file for details

🔗 Related Projects

• Fly.io - The platform this tool manages
• flyctl - The CLI tool this interfaces with
• Model Context Protocol - The protocol used for integration