feat: lazy-start Neko connection on first /display/webrtc request

The relay no longer connects to Neko eagerly on server startup.
Instead, the Neko WebRTC connection is established on-demand when
the first client hits /display/webrtc, avoiding the cost of an
idle WebRTC session when no one is consuming the screen stream.

- Move reconnect loop into Relay.ensureRunning() behind sync.Once
- HandleWebSocket triggers ensureRunning() then waits up to 15s
  for the relay to become ready
- Simplify main.go: no background goroutine, just register endpoint

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: rgarcia

server/cmd/api/main.go

@@ -138,9 +138,10 @@ func main() {
 
 	// WebRTC relay: connects to Neko as a headless viewer and re-serves
 	// the VP8 video stream to external WebRTC clients via a single
-	// WebSocket signaling endpoint.
+	// WebSocket signaling endpoint. The Neko connection is lazy —
+	// it only starts when the first client connects.
 	if config.WebRTCRelayEnabled {
-		relay, err := webrtcscreen.NewRelay(webrtcscreen.RelayConfig{
+		relay, err := webrtcscreen.NewRelay(ctx, webrtcscreen.RelayConfig{
 			NekoBaseURL: "http://127.0.0.1:8080",
 			NekoUser:    "admin",
 			NekoPass:    adminPassword,
@@ -150,24 +151,9 @@ func main() {
 			slogger.Error("failed to create webrtc relay", "err", err)
 			os.Exit(1)
 		}
-		go func() {
-			defer relay.Close()
-			for {
-				err := relay.Start(ctx)
-				if ctx.Err() != nil {
-					return
-				}
-				slogger.Warn("webrtc relay disconnected, reconnecting in 3s", "err", err)
-				select {
-				case <-ctx.Done():
-					return
-				case <-time.After(3 * time.Second):
-				}
-			}
-		}()
 
 		r.Get("/display/webrtc", relay.HandleWebSocket)
-		slogger.Info("webrtc relay endpoint enabled at /display/webrtc")
+		slogger.Info("webrtc relay endpoint registered at /display/webrtc (lazy start)")
 	}
 
 	srv := &http.Server{

server/lib/webrtcscreen/relay.go

@@ -20,15 +20,21 @@ import (
 // WebRTC clients. The API server mounts HandleWebSocket on a
 // single endpoint (e.g., /display/webrtc) — that's all external
 // clients need to connect and receive the live screen.
+//
+// The Neko connection is lazy: it is only established when the
+// first client connects via HandleWebSocket.
 type Relay struct {
 	logger *slog.Logger
 	cfg    RelayConfig
+	ctx    context.Context
 
 	mu         sync.RWMutex
 	localTrack *webrtc.TrackLocalStaticRTP
 	nekoPC     *webrtc.PeerConnection
 	nekoWS     *cws.Conn
 	ready      chan struct{} // closed when localTrack is receiving data
+
+	startOnce sync.Once
 }
 
 type RelayConfig struct {
@@ -38,7 +44,7 @@ type RelayConfig struct {
 	Logger      *slog.Logger
 }
 
-func NewRelay(cfg RelayConfig) (*Relay, error) {
+func NewRelay(ctx context.Context, cfg RelayConfig) (*Relay, error) {
 	if cfg.Logger == nil {
 		cfg.Logger = slog.Default()
 	}
@@ -54,11 +60,35 @@ func NewRelay(cfg RelayConfig) (*Relay, error) {
 	return &Relay{
 		logger:     cfg.Logger.With("component", "webrtc-relay"),
 		cfg:        cfg,
+		ctx:        ctx,
 		localTrack: localTrack,
 		ready:      make(chan struct{}),
 	}, nil
 }
 
+// ensureRunning starts the Neko connection loop in the background
+// on the first call. Subsequent calls are no-ops.
+func (r *Relay) ensureRunning() {
+	r.startOnce.Do(func() {
+		r.logger.Info("first client request, starting neko connection")
+		go func() {
+			defer r.Close()
+			for {
+				err := r.Start(r.ctx)
+				if r.ctx.Err() != nil {
+					return
+				}
+				r.logger.Warn("webrtc relay disconnected, reconnecting in 3s", "err", err)
+				select {
+				case <-r.ctx.Done():
+					return
+				case <-time.After(3 * time.Second):
+				}
+			}
+		}()
+	})
+}
+
 // Start connects to Neko and begins relaying video. It blocks until
 // the Neko connection drops or ctx is cancelled. Callers should call
 // Start in a loop for automatic reconnection.
@@ -229,6 +259,18 @@ func (r *Relay) Start(ctx context.Context) error {
 // After the exchange, WebRTC media flows directly. The WebSocket
 // can be closed.
 func (r *Relay) HandleWebSocket(w http.ResponseWriter, req *http.Request) {
+	r.ensureRunning()
+
+	// Wait for the relay to be connected to Neko before accepting the client.
+	select {
+	case <-r.Ready():
+	case <-time.After(15 * time.Second):
+		http.Error(w, "relay not ready", http.StatusServiceUnavailable)
+		return
+	case <-req.Context().Done():
+		return
+	}
+
 	ws, err := cws.Accept(w, req, nil)
 	if err != nil {
 		r.logger.Error("websocket accept failed", "error", err)