Merge branch 'remote'

Author: ericdallo

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Auto-retry Anthropic streams that end prematurely with empty responses, and auto-continue when response is truncated (e.g. unclosed code blocks).
 - Fix resume crash when conversation contained server-side tool use (e.g. web search).
+- Add remote web control server for browser-based chat observation and control via `web.eca.dev`. #333
 
 ## 0.115.5
 

docs/config.json

@@ -332,6 +332,41 @@
         ]
       }
     },
+    "remote": {
+      "type": "object",
+      "description": "Remote web control server configuration. When enabled, starts an embedded HTTP server allowing a web frontend (web.eca.dev) to observe and control chat sessions in real-time.",
+      "markdownDescription": "Remote web control server configuration. When enabled, starts an embedded HTTP server allowing a web frontend (`web.eca.dev`) to observe and control chat sessions in real-time.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enables the remote HTTP server.",
+          "markdownDescription": "Enables the remote HTTP server."
+        },
+        "host": {
+          "type": "string",
+          "description": "Host used in the logged URL for web.eca.dev to connect back to. Can be a LAN IP, public IP, domain, or tunnel URL. When unset, auto-detected via InetAddress/getLocalHost.",
+          "markdownDescription": "Host used in the logged URL for `web.eca.dev` to connect back to. Can be a LAN IP, public IP, domain, or tunnel URL. When unset, auto-detected via `InetAddress/getLocalHost`.",
+          "examples": [
+            "192.168.1.42",
+            "myserver.example.com"
+          ]
+        },
+        "port": {
+          "type": "integer",
+          "description": "Port the HTTP server listens on. When unset, tries port 7777, then 7778, 7779, etc. up to 10 attempts.",
+          "markdownDescription": "Port the HTTP server listens on. When unset, tries port `7777`, then `7778`, `7779`, etc. up to 10 attempts.",
+          "examples": [
+            7777
+          ]
+        },
+        "password": {
+          "type": "string",
+          "description": "Auth token for Bearer authentication. When unset, a 32-byte hex token is auto-generated and logged to stderr.",
+          "markdownDescription": "Auth token for Bearer authentication. When unset, a 32-byte hex token is auto-generated and logged to stderr."
+        }
+      }
+    },
     "network": {
       "type": "object",
       "description": "Network configuration for custom CA certificates and mTLS client certificates. Values support dynamic string interpolation (e.g. '${env:SSL_CERT_FILE}').",

docs/config/remote.md

@@ -0,0 +1,120 @@
+---
+description: "Configure ECA Remote: control your ECA session from a web browser via Tailscale or LAN."
+---
+
+# Remote
+
+ECA Remote lets you control and observe your ECA session from a web browser. When enabled, ECA starts an embedded HTTP server that a web frontend can connect to in real-time.
+
+## Configuration
+
+```javascript title="~/.config/eca/config.json"
+{
+  "remote": {
+    "enabled": true,
+    // optional — useful for specifying custom dns like tailscale or your local ip
+    "host": "192.168.1.42",
+    // optional — defaults to 7777 (auto-increments if busy)
+    "port": 7777,
+    // optional — a random pass is auto-generated when unset
+    "password": "my-secret-token"
+  }
+}
+```
+
+Minimal setup — just enable it and ECA handles the rest:
+
+```javascript title="~/.config/eca/config.json"
+{
+  "remote": {
+    "enabled": true
+  }
+}
+```
+
+When the server starts, ECA logs the connection URL and auth token to stderr and welcome message. The URL is a deep-link that you can open directly in the browser:
+
+```
+https://web.eca.dev?host=192.168.1.42:7777&pass=a3f8b2c1...&protocol=https
+```
+
+## Connection Methods
+
+There are three ways to connect the web frontend to your ECA session.
+
+### Direct (LAN / Private IP)
+
+The simplest approach — connect directly from `https://web.eca.dev` to your machine's private IP.
+
+1. Enable remote in your config:
+
+    ```javascript title="~/.config/eca/config.json"
+    {
+      "remote": {
+        "enabled": true,
+        "password": "something" // optioal - or ${env:MY_PASS}
+      }
+    }
+    ```
+
+2. Start ECA — it will log the connection URL or auth token with random pass.
+3. Open `https://web.eca.dev` and enter your machine's LAN IP (e.g. `192.168.1.42`) and password
+4. Chrome will show a **Local Network Access** permission prompt — click **Allow**
+
+!!! note "Firewall"
+    Make sure your firewall allows incoming TCP connections on ports `7777`–`7787` (the default ECA port range) from your LAN.
+    ECA start using `7777` and so one for each server running in your machine.
+
+### Tailscale / VPN
+
+For a seamless HTTPS-to-HTTPS connection with no browser prompts. [Tailscale](https://tailscale.com) (free) creates a secure private network between your devices with valid HTTPS certificates.
+
+1. Install Tailscale and enable [HTTPS certificates](https://tailscale.com/kb/1153/enabling-https)
+2. Set `host` to your machine's Tailscale domain name:
+
+    ```javascript title="~/.config/eca/config.json"
+    {
+      "remote": {
+        "enabled": true,
+        "password": "something-here",
+        "host": "my-machine.tail1234.ts.net" // optional - just to get url easily when starting
+      }
+    }
+    ```
+
+3. Start ECA — it will log a connection URL
+4. Open `https://web.eca.dev` and paste the connection URL or manually enter host and password
+
+Because Tailscale provides valid HTTPS certificates for your machine, the browser connects without any mixed-content issues or permission prompts.
+
+### Local Docker
+
+If you prefer to keep everything over plain HTTP, you can run the web frontend locally. This avoids all browser security restrictions.
+
+1. Enable remote in your config:
+
+    ```javascript title="~/.config/eca/config.json"
+    {
+      "remote": {
+        "enabled": true,
+        "password": "something-here"
+      }
+    }
+    ```
+
+2. Run the web frontend locally via Docker, usually in the same machine where server is running:
+
+    ```bash
+    docker run --pull=always -p 8080:80 ghcr.io/editor-code-assistant/eca-web
+    ```
+
+3. Start ECA — it will log the connection URL and auth token
+4. Open `http://localhost:8080` and paste the connection URL
+
+## Web UI
+
+The web frontend provides a connect form where you enter the host and password (or use the deep-link URL logged by ECA).
+
+**Auto-discovery** — When you enter a host and click "Discover", the web UI scans ports `7777`–`7787` in parallel and finds all running ECA instances automatically. This is the default port range ECA uses when auto-assigning ports.
+
+**Multi-session** — You can connect to multiple ECA instances simultaneously. Each connection appears as a tab in the top bar, letting you switch between sessions.

docs/overrides/home.html

@@ -1719,6 +1719,13 @@ <h3 class="eca-feature__title">Plugins</h3>
               <p class="eca-feature__desc">Extend ECA with community plugins &mdash; bundles of tools, rules, skills, and more from the marketplace.</p>
             </div>
           </a>
+          <a href="config/remote" class="eca-feature">
+            <div class="eca-feature__icon">🌐</div>
+            <div class="eca-feature__body">
+              <h3 class="eca-feature__title">Remote</h3>
+              <p class="eca-feature__desc">Observe and control your chat session from a browser via an embedded web server and web.eca.dev.</p>
+            </div>
+          </a>
         </div>
       </div>