Gretl

Product Introduction

1. Definition: Gretl is a cross-platform localhost port manager and developer productivity tool. Technically, it is a system daemon that provides a unified control surface (CLI, GUI, SDKs, browser extension) for monitoring and managing all network services running on a developer's local machine.
2. Core Value Proposition: Gretl exists to eliminate the chaos of local development environments by replacing port numbers with memorable names. Its core value is providing name-based service management, allowing developers to control their entire stack through intuitive commands like gr start jobs instead of memorizing and managing individual ports like :7400.

Main Features

1. Unified Multi-Surface Control: Gretl operates via a single local daemon that powers four distinct interfaces. The Gretl CLI (gr start, gr status) offers scriptable terminal control. The native desktop app for macOS, Windows, and Linux provides a real-time GUI with CPU/memory metrics. The Chrome/Firefox/Edge browser extension gives one-click access to services from any tab. Cross-language SDKs (Node.js, Python, Go, Ruby) offer programmatic control within application code.
2. Service Grouping and Dependency Management: Developers can define logical collections of services in a version-controlled gr.toml configuration file. The gr group start @jobs command boots an entire stack (e.g., a frontend, API, and worker) in the correct order with configurable health checks. This feature is essential for managing microservices architectures and complex development environments.
3. Automated Service Detection and Adoption: The gr detect command scans the local machine for any listening ports (from tools like Vite, Next.js, Postgres, or ad-hoc scripts) and offers to "adopt" them into Gretl's management system. This automatic port discovery seamlessly integrates existing workflows without manual configuration.
4. Built-in MCP Server for AI Integration: Gretl ships with a Model Context Protocol (MCP) server. By adding one line to a Claude AI configuration file, developers can grant their AI assistant real-time, conversational control over their localhost ports, enabling queries like "Which services are down?" and commands like "Start the lighthouse-webapp group" directly within chat.

Problems Solved

1. Pain Point: The cognitive overhead and errors associated with managing multiple localhost ports (e.g., "What's running on port 3001? Did I start the database on 5432 or 5433?"). This leads to port conflicts, PID drift, and wasted time debugging environment issues.
2. Target Audience: The primary personas are Full-Stack Developers, DevOps Engineers, and Engineering Managers working with modern, service-oriented applications (React/Vite frontends, Node.js/Python/Go backends, databases, message queues). It is particularly valuable for teams practicing microservices development where numerous independent services must run concurrently.
3. Use Cases: Onboarding new team members who can run gr group up --all from a shared gr.toml to get an identical environment. Context-switching between projects without manually stopping/starting services. Providing temporary access to a locally running service for a colleague via Gretl's remote port access feature. Integrating local service management into CI/CD scripts using the Gretl SDK.

Unique Advantages

1. Differentiation: Unlike simple process managers (like forever or pm2) that manage by PID, or manual .env file configurations, Gretl manages the entire localhost network namespace. It provides a persistent, name-based registry that survives reboots and is shareable across machines. Unlike cloud-based development environments, it remains local-first and offline-capable.
2. Key Innovation: The combination of a persistent local daemon with a real-time Server-Sent Events (SSE) stream ensures all interfaces (GUI, CLI, extension) show perfectly synchronized, live status without polling. The commit-able gr.toml file acts as a declarative, version-controlled blueprint for the entire team's local infrastructure, solving environment consistency.

Frequently Asked Questions (FAQ)

1. Is Gretl a replacement for Docker or Kubernetes? No, Gretl is a complementary tool for local development. It manages processes and ports on your host machine, while Docker/Kubernetes are containerization and orchestration platforms. Gretl can manage Dockerized services running locally by controlling their exposed host ports.
2. How does Gretl handle security and data privacy? The Gretl daemon runs exclusively on 127.0.0.1 (localhost). By default, it includes no telemetry and does not phone home. For team features, connections are encrypted, and the Enterprise plan offers a self-hosted control plane to ensure no data leaves your private network.
3. Can I use Gretl with my existing development tools and workflows? Yes, Gretl is designed to work alongside existing tools. Its detect command can adopt already-running processes from Vite, Rails, Django, etc. You can incrementally adopt Gretl by registering key services without changing how they are launched.
4. What is the difference between the free Solo plan and the paid Team plan? The free Solo plan includes all core functionality for an individual: the desktop app, CLI, SDKs, and browser extension. The paid Team plan ($15/seat/month) adds collaborative features: shared gr.toml catalogs, org-wide service name resolution, SSO, audit logs, and priority support.
5. How do I define service dependencies and startup order in Gretl? Dependencies and health checks are configured in the gr.toml file using the [groups] and [services] sections. You can specify a depends_on list for services and define a health_check endpoint (e.g., an HTTP path or TCP probe) that Gretl will monitor before marking a service as "ready."