[Feature Request] Expose IPC / API interface (JSON IPC, HTTP, or WebSockets) for programmatic agent control and remote configuration

[nglmercer]

Feature Request

Summary

Add a local or remote programmatic API (such as JSON-over-IPC/Unix domain sockets, a local HTTP REST server, or WebSockets) to playit-agent. This would enable external scripts, agentic workflows, and Model Context Protocol (MCP) servers to dynamically manage tunnels, inspect status, and manage account authentication programmatically.

---

Motivation & Use Cases

Currently, playit-agent is primarily controlled via its CLI / interactive interface. Enabling a structured API/IPC interface unlocks significant automation capabilities:

1. AI Agent & MCP Integration:
   • Allows LLM agents or MCP servers (e.g., custom Claude / Cursor tools) to dynamically request public tunnels, inspect active routes, and retrieve connection details on demand.
2. Remote / Headless Management:
   • Facilitates lightweight web dashboards, orchestration scripts, or game server panels (like Pterodactyl or custom daemons) to manage playit tunnels without spawning and scraping sub-process CLI outputs.
3. Automated Tunnel Lifecycle:
   • Applications using playit-agent as a sidecar can programmatically check health status, listen for reconnect events, or trigger tunnel creation/deletion via structured JSON payloads.

---

Proposed Options / Interfaces

Depending on architectural preference and security boundaries, a few approaches could be considered:

• Option A: Local IPC (Unix Sockets / Named Pipes)
  • Best for local agents and sidecar processes.
  • Standard JSON-RPC or line-delimited JSON over playit.sock (or Windows Named Pipe).
• Option B: Local HTTP / WebSockets Server
  • Bindable to 127.0.0.1:<port> with optional bearer token / API key authentication.
  • WebSockets would allow real-time status updates (tunnel state changes, ping telemetry, connection loss).
• Option C: Command-Line --json / Stdio IPC Mode
  • A dedicated process mode (playit-agent --stdio-ipc or --api) that communicates over stdin/stdout using JSON events.

---

Capabilities / Endpoints to Expose

• GET /status or status RPC: Get active tunnel statuses, assigned public IPs/ports, ping times, and agent health.
• POST /tunnels or create_tunnel: Dynamically allocate a new tunnel for a specified local port/proto (e.g., TCP/UDP).
• DELETE /tunnels/:id: Tear down a running tunnel.
• GET /account or claim: Retrieve current agent registration state / claim URL if unlinked.

---

Additional Context

Exposing standard tools or an MCP toolset for playit-agent makes it effortless to integrate zero-trust tunneling into modern developer workflows and automated deployments.

Would the maintainers be open to an API abstraction layer for this? If there is an existing preferred direction or internal architectural pattern for this, I'd love to hear your thoughts!