feat(examples): add vps-web-portal React application

Author: tacshade

examples/vps-web-portal/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/vps-web-portal/README.md

@@ -0,0 +1,93 @@
+# VPS Web Portal (Tandem Engine Examples)
+
+This project contains a highly-polished, multi-page showcase that connects directly to the `tandem-engine` running as a headless server on a Linux VPS. It provides a secure UI wrapper and a Node/Express backend that handles reverse-proxying and authentication, safeguarding the engine's open ports from the public internet.
+
+## Prerequisites
+
+- A Linux VPS (Ubuntu/Debian recommended)
+- Node.js (v18+)
+- PM2 (optional, for running the project in the background)
+- The [Tandem Engine CLI](https://github.com/your-org/tandem)
+
+## 1. Setup the Tandem Engine
+
+First, install the tandem engine directly on your VPS. Provide it access to local AI providers or proxies as well as MCP components.
+
+Generate a secure Server Token. Do NOT lose this.
+
+```bash
+tandem-engine token generate
+```
+
+_(Copy the generated UUID. We'll need it later)._
+
+Start the headless engine running in the background. It will bind to `localhost:39731` by default.
+
+```bash
+nohup tandem-engine serve --headless &
+```
+
+_(Alternatively, run it using a robust service manager like SystemD)._
+
+## 2. Setup the Web Portal
+
+Clone this repository or copy the `vps-web-portal` directory to your VPS.
+
+Navigate to the project directory and install the required dependencies:
+
+```bash
+cd vps-web-portal
+npm install
+```
+
+### Environment Configuration
+
+Create a `.env` file in the root of the portal directory:
+
+```env
+# The port the Node/Express proxy will listen on (Publicly accessible)
+PORT=80
+
+# The Secret Key used to login to the secure Web Portal URL
+VITE_PORTAL_KEY=my_secret_password_123
+
+# The Token generated by 'tandem-engine token generate' in Step 1
+VITE_ENGINE_TOKEN=your-generated-tandem-token-here
+
+# (Optional) Engine local address
+VITE_TANDEM_ENGINE_URL=http://127.0.0.1:39731
+```
+
+## 3. Build & Run
+
+Build the Vite React frontend for production:
+
+```bash
+npm run build
+```
+
+Start the Node.js Express server to host the application. We recommend using PM2 to keep the server alive forever:
+
+```bash
+npm install -g pm2
+pm2 start npm --name "tandem-portal" -- run start:server
+```
+
+_(Alternatively, you can just run `npm run start:server` directly for testing)._
+
+## Usage
+
+Visit your server's public IP or Domain name in your browser (e.g., `http://your-server-ip:80`).
+You will be greeted by the Login portal. Enter the `VITE_PORTAL_KEY` you configured earlier to unlock the dashboards.
+
+### Included Dashboards
+
+1. **Deep Research:** Unleash an agent to scour the public web and answer heavy research questions.
+2. **Parallel Swarm:** Submit an idea and watch 3 distinct personas debate its merits simultaneously using the Parallel APIs.
+3. **Interactive RPG:** An AI Text Adventure game demonstrating the `Questions API` over Streaming SSE.
+4. **Second Brain:** Grant an agent local system context using Local MCP (Model Context Protocol).
+5. **Connectors:** Setup Slack, Discord, or Telegram bots so your team can @ the engine directly.
+
+## Security Note
+
+**Never** expose port `39731` to `0.0.0.0` or disable the firewall on a public VPS. Only the Reverse Proxy (this portal) should converse with the background Tandem engine locally, proxying authenticated REST and SSE requests.

examples/vps-web-portal/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

examples/vps-web-portal/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>vps-web-portal</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>