feat: Add web terminal interface with browser-based terminal access (#351)

Adds a web terminal interface that provides browser-based access to the
CLI chat interface. Users can now run `infer chat --web` to start a web
server and access the terminal from any browser with tabbed sessions.

Key features:
- Browser-based terminal using xterm.js with Tokyo Night theme
- Multiple independent tabbed sessions with isolated containers
- Automatic session cleanup after configurable inactivity period
- Remote access capability with security considerations documented
- Graceful shutdown handling for all sessions and containers

The implementation includes PTY management, WebSocket communication,
session tracking, and comprehensive documentation.

Author: edenreich

.infer/config.yaml

@@ -620,3 +620,8 @@ compact:
   enabled: true
   auto_at: 80
   keep_first_messages: 2
+web:
+  enabled: false
+  port: 3000
+  host: localhost
+  session_inactivity_mins: 5

.infer/mcp.yaml

@@ -13,7 +13,7 @@ servers:
     host: localhost
     scheme: http
     ports:
-      - "3000:8010"
+      - "8010:8010"
     path: /mcp
     oci: mekayelanik/context7-mcp:stable
     startup_timeout: 90

README.md

@@ -68,6 +68,7 @@ and management of inference services.
 - **Extensible Shortcuts System**: Create custom commands with AI-powered snippets - [Learn more →](docs/shortcuts-guide.md)
 - **MCP Server Support**: Direct integration with Model Context Protocol servers for extended tool capabilities -
   [Learn more →](docs/mcp-integration.md)
+- **Web Terminal Interface**: Browser-based terminal access with tabbed sessions for remote access and multi-session workflows - [Learn more →](docs/web-terminal.md)
 
 ## Installation
 
@@ -180,6 +181,7 @@ Now that you're up and running, explore these guides:
 - **[Commands Reference](docs/commands-reference.md)** - Complete command documentation
 - **[Tools Reference](docs/tools-reference.md)** - Available tools for LLMs
 - **[Configuration Guide](docs/configuration-reference.md)** - Full configuration options
+- **[Web Terminal](docs/web-terminal.md)** - Browser-based terminal interface
 - **[Shortcuts Guide](docs/shortcuts-guide.md)** - Custom shortcuts and AI-powered snippets
 - **[A2A Agents](docs/agents-configuration.md)** - Agent-to-agent communication setup
 
@@ -199,11 +201,25 @@ infer init --userspace  # Initialize user-level configuration
 **`infer chat`** - Start an interactive chat session with model selection
 
 ```bash
+# Terminal mode (default)
 infer chat
+
+# Web terminal mode with browser interface
+infer chat --web
+infer chat --web --port 8080  # Custom port
 ```
 
 **Features:** Model selection, real-time streaming, scrollable history, three agent modes (Standard/Plan/Auto-Accept).
 
+**Web Mode Features:**
+
+- Browser-based terminal using xterm.js
+- Multiple independent tabbed sessions
+- Automatic session cleanup on inactivity
+- Each tab manages its own `infer chat` process with isolated containers
+- Access from any device on the network
+- Responsive terminal sizing with horizontal padding
+
 **`infer agent`** - Execute autonomous tasks in background mode
 
 ```bash
@@ -383,6 +399,10 @@ infer chat --model "anthropic/claude-4"
 - **chat.theme** - Chat interface theme (default: `tokyo-night`)
 - **chat.status_bar.enabled** - Enable/disable status bar (default: `true`)
 - **chat.status_bar.indicators** - Configure individual status indicators (all enabled by default except `max_output`)
+- **web.enabled** - Enable web terminal mode (default: `false`)
+- **web.port** - Web server port (default: `3000`)
+- **web.host** - Web server host (default: `localhost`)
+- **web.session_inactivity_mins** - Session timeout in minutes (default: `5`)
 
 ### Environment Variables
 
@@ -393,6 +413,11 @@ export INFER_GATEWAY_URL="http://localhost:8080"
 export INFER_AGENT_MODEL="deepseek/deepseek-chat"
 export INFER_TOOLS_BASH_ENABLED=true
 export INFER_CHAT_THEME="tokyo-night"
+
+# Web terminal configuration
+export INFER_WEB_PORT=3000
+export INFER_WEB_HOST="localhost"
+export INFER_WEB_SESSION_INACTIVITY_MINS=5
 ```
 
 **Format:** `INFER_<PATH>` where dots become underscores.
@@ -714,6 +739,38 @@ infer config tools web-search enable
 infer config show
 ```
 
+### Web Terminal Example
+
+```bash
+# Start web terminal server
+infer chat --web
+
+# Open browser to http://localhost:3000
+# Click "+" to create new terminal tabs
+# Each tab is an independent chat session
+
+# Custom port for remote access
+infer chat --web --port 8080 --host 0.0.0.0
+
+# Configure via config file
+cat > .infer/config.yaml <<EOF
+web:
+  enabled: true
+  port: 3000
+  host: "localhost"
+  session_inactivity_mins: 10  # Auto-cleanup after 10 minutes
+EOF
+
+infer chat --web  # Uses config file settings
+```
+
+**Use Cases:**
+
+- Remote access to CLI from any device
+- Multiple parallel chat sessions in browser tabs
+- Team collaboration with shared terminal access
+- Persistent sessions with automatic cleanup
+
 ## Development
 
 For development, use [Task](https://taskfile.dev) for build automation:

cmd/chat.go

@@ -5,32 +5,46 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"os/signal"
 	"path/filepath"
 	"strings"
+	"sync"
+	"syscall"
 	"time"
 
 	tea "github.com/charmbracelet/bubbletea"
+	cobra "github.com/spf13/cobra"
+	viper "github.com/spf13/viper"
+
 	config "github.com/inference-gateway/cli/config"
 	app "github.com/inference-gateway/cli/internal/app"
 	clipboard "github.com/inference-gateway/cli/internal/clipboard"
 	container "github.com/inference-gateway/cli/internal/container"
 	domain "github.com/inference-gateway/cli/internal/domain"
+	logger "github.com/inference-gateway/cli/internal/logger"
+	web "github.com/inference-gateway/cli/internal/web"
 	sdk "github.com/inference-gateway/sdk"
-	cobra "github.com/spf13/cobra"
-	viper "github.com/spf13/viper"
 )
 
 var chatCmd = &cobra.Command{
 	Use:   "chat",
 	Short: "Start an interactive chat session with model selection",
 	Long: `Start an interactive chat session where you can select a model from a dropdown
 and have a conversational interface with the inference gateway.`,
-	RunE: func(_ *cobra.Command, args []string) error {
+	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg, err := getConfigFromViper()
 		if err != nil {
 			return fmt.Errorf("failed to load config: %w", err)
 		}
 
+		webMode, _ := cmd.Flags().GetBool("web")
+		if webMode {
+			if cmd.Flags().Changed("port") {
+				cfg.Web.Port, _ = cmd.Flags().GetInt("port")
+			}
+			return StartWebChatSession(cfg, V)
+		}
+
 		if !isInteractiveTerminal() {
 			return runNonInteractiveChat(cfg, V)
 		}
@@ -44,10 +58,31 @@ func StartChatSession(cfg *config.Config, v *viper.Viper) error {
 	_ = clipboard.Init()
 
 	services := container.NewServiceContainer(cfg, v)
-	defer func() {
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-		defer cancel()
-		_ = services.Shutdown(ctx)
+
+	sigChan := make(chan os.Signal, 1)
+	signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM, syscall.SIGHUP)
+
+	shutdownComplete := make(chan struct{})
+	var shutdownOnce sync.Once
+
+	doShutdown := func() {
+		shutdownOnce.Do(func() {
+			logger.Info("Received shutdown signal, cleaning up...")
+			ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+			defer cancel()
+			if err := services.Shutdown(ctx); err != nil {
+				logger.Error("Error during shutdown", "error", err)
+			}
+			close(shutdownComplete)
+		})
+	}
+
+	defer doShutdown()
+
+	go func() {
+		<-sigChan
+		doShutdown()
+		os.Exit(0)
 	}()
 
 	if err := services.GetGatewayManager().EnsureStarted(); err != nil {
@@ -134,6 +169,12 @@ func StartChatSession(cfg *config.Config, v *viper.Viper) error {
 	return nil
 }
 
+// StartWebChatSession starts a web-based chat session with PTY and WebSocket
+func StartWebChatSession(cfg *config.Config, v *viper.Viper) error {
+	server := web.NewWebTerminalServer(cfg, v)
+	return server.Start()
+}
+
 func validateAndSetDefaultModel(modelService domain.ModelService, models []string, defaultModel string) string {
 	modelFound := false
 	for _, model := range models {
@@ -197,7 +238,7 @@ func isInteractiveTerminal() bool {
 func runNonInteractiveChat(cfg *config.Config, v *viper.Viper) error {
 	services := container.NewServiceContainer(cfg, v)
 	defer func() {
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
 		defer cancel()
 		_ = services.Shutdown(ctx)
 	}()
@@ -302,4 +343,6 @@ func processStreamingOutput(events <-chan domain.ChatEvent) error {
 
 func init() {
 	rootCmd.AddCommand(chatCmd)
+	chatCmd.Flags().Bool("web", false, "Start web terminal interface")
+	chatCmd.Flags().Int("port", 0, "Web server port (default: 3000)")
 }

cmd/root.go

@@ -79,6 +79,11 @@ func initConfig() { // nolint:funlen
 	v.SetDefault("compact.enabled", defaults.Compact.Enabled)
 	v.SetDefault("compact.auto_at", defaults.Compact.AutoAt)
 	v.SetDefault("compact.keep_first_messages", defaults.Compact.KeepFirstMessages)
+	v.SetDefault("web", defaults.Web)
+	v.SetDefault("web.enabled", defaults.Web.Enabled)
+	v.SetDefault("web.port", defaults.Web.Port)
+	v.SetDefault("web.host", defaults.Web.Host)
+	v.SetDefault("web.session_inactivity_mins", defaults.Web.SessionInactivityMins)
 	v.SetDefault("git", defaults.Git)
 	v.SetDefault("storage", defaults.Storage)
 	v.SetDefault("conversation", defaults.Conversation)

config/config.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"regexp"
 	"strings"
+	"sync"
 )
 
 const (
@@ -40,6 +41,7 @@ type Config struct {
 	Pricing          PricingConfig          `yaml:"pricing" mapstructure:"pricing"`
 	Init             InitConfig             `yaml:"init" mapstructure:"init"`
 	Compact          CompactConfig          `yaml:"compact" mapstructure:"compact"`
+	Web              WebConfig              `yaml:"web" mapstructure:"web"`
 	configDir        string
 }
 
@@ -263,6 +265,14 @@ type CompactConfig struct {
 	KeepFirstMessages int  `yaml:"keep_first_messages" mapstructure:"keep_first_messages"`
 }
 
+// WebConfig contains web terminal settings
+type WebConfig struct {
+	Enabled               bool   `yaml:"enabled" mapstructure:"enabled"`
+	Port                  int    `yaml:"port" mapstructure:"port"`
+	Host                  string `yaml:"host" mapstructure:"host"`
+	SessionInactivityMins int    `yaml:"session_inactivity_mins" mapstructure:"session_inactivity_mins"`
+}
+
 // SystemRemindersConfig contains settings for dynamic system reminders
 type SystemRemindersConfig struct {
 	Enabled      bool   `yaml:"enabled" mapstructure:"enabled"`
@@ -921,6 +931,12 @@ Write the AGENTS.md file to the project root when you have gathered enough infor
 			AutoAt:            80,
 			KeepFirstMessages: 2,
 		},
+		Web: WebConfig{
+			Enabled:               false,
+			Port:                  3000,
+			Host:                  "localhost",
+			SessionInactivityMins: 5,
+		},
 	}
 }
 
@@ -1242,18 +1258,42 @@ func ActionID(namespace KeyNamespace, action string) string {
 	return string(namespace) + "_" + action
 }
 
+// Global port registry to prevent race conditions when allocating ports
+var (
+	allocatedPorts = make(map[int]bool)
+	portMutex      sync.Mutex
+)
+
 // FindAvailablePort finds the next available port starting from basePort
 // It checks up to 100 ports after the base port
 // Binds to all interfaces (0.0.0.0) to match Docker's behavior
+// Thread-safe: uses global port registry to prevent race conditions
 func FindAvailablePort(basePort int) int {
+	portMutex.Lock()
+	defer portMutex.Unlock()
+
 	for port := basePort; port < basePort+100; port++ {
+		if allocatedPorts[port] {
+			continue
+		}
+
 		address := fmt.Sprintf(":%d", port)
 		listener, err := net.Listen("tcp", address)
 		if err != nil {
 			continue
 		}
 		_ = listener.Close()
+
+		allocatedPorts[port] = true
 		return port
 	}
 	return basePort
 }
+
+// ReleasePort releases a previously allocated port
+// Should be called when containers are stopped
+func ReleasePort(port int) {
+	portMutex.Lock()
+	defer portMutex.Unlock()
+	delete(allocatedPorts, port)
+}