openclaw-syncralis 2.1.0 → 2.2.0

package/.env.example

@@ -1,5 +1,8 @@
-PUBLIC_TUNNEL_URL=https://your-domain.ngrok-free.app
-URL_SIGNING_SECRET= "your_custom_32_character_secret_here",
+WORKSPACE_DIR=""
+PUBLIC_TUNNEL_URL="https://your-domain.ngrok-free.app"
+NGROK_AUTHTOKEN=your_ngrok_authtoken_here
+NGROK_API_PORT=4040
+URL_SIGNING_SECRET="your_custom_32_character_secret_here"
 TAVILY_API_KEY=your_tavily_key_here
 BRAVE_API_KEY=your_brave_key_here
 FILE_SERVER_HOST=127.0.0.1

package/README.md

@@ -59,8 +59,17 @@ clawhub login pslkk/openclaw-syncralis
 Syncralis is designed as a hybrid tool. It works perfectly on your native operating system (Windows/Mac/Linux) or securely inside a Dockerized environment. 
 
 
-Choose the deployment method that matches your OpenClaw setup below.
+#### The Workspace Directory (`WORKSPACE_DIR`):
 
+The gateway needs a secure folder to store and manage files. We have designed this to be fully automated, but flexible for power users:
+
+***Native / Default Install (Recommended):** Leave `WORKSPACE_DIR=` completely empty (or omit it). The gateway will automatically detect your OS and securely store files in your native home directory: `~/.openclaw/workspace`.
+
+***Docker / Custom Environments:** If you are running OpenClaw inside a custom Docker container or want to force the gateway to use a specific volume mount, define the absolute path here:
+`WORKSPACE_DIR=/custom/path/to/workspace`
+
+
+### Choose the deployment method that matches your OpenClaw setup below:
 
 ### Option 1: Native NPM Setup (Without Docker)
 
@@ -69,8 +78,17 @@ When running OpenClaw natively on your host machine, Syncralis spins up a secure
 
 1. Open a new terminal window and run Ngrok to expose the default port:
 
+   *Note: For a production setup, we highly recommend using your static URL from the Ngrok dashboard so your tunnel never changes.*
+
   ```bash
 
+  # 1. Authenticate your terminal (Run this once)
+  ngrok config add-authtoken your_ngrok_token_here
+
+  # 2. Start the tunnel using your static URL (Recommended)
+  ngrok http --url your-custom-url.ngrok-free.app 8080
+
+  # Or, using a dynamic URL (Testing only)
   ngrok http 8080
 
   ```
@@ -85,8 +103,10 @@ When running OpenClaw natively on your host machine, Syncralis spins up a secure
         "command": "openclaw-syncralis",
         "env": {
           "NODE_ENV": "production",
-          "FILE_SERVER_HOST": "127.0.0.1", 
+          "FILE_SERVER_HOST": "127.0.0.1",
+          "WORKSPACE_DIR": "",
           "PUBLIC_TUNNEL_URL": "https://your-ngrok-url.ngrok-free.app",
+          "NGROK_API_PORT": 4040,
           "URL_SIGNING_SECRET": "your_custom_32_character_secret_here",
           "TAVILY_API_KEY": "your_tavily_key",
           "BRAVE_API_KEY": "your_brave_key"
@@ -114,7 +134,9 @@ OpenClaw often executes tools as ephemeral child processes. In a containerized s
         "env": {
           "NODE_ENV": "production",
           "FILE_SERVER_HOST": "0.0.0.0",
+          "WORKSPACE_DIR": "",
           "PUBLIC_TUNNEL_URL": "https://your-static-domain.ngrok-free.app",
+          "NGROK_API_PORT": 4040,
           "URL_SIGNING_SECRET": "your_custom_32_character_secret_here",
           "TAVILY_API_KEY": "your_tavily_key",
           "BRAVE_API_KEY": "your_brave_key"
@@ -153,8 +175,9 @@ services:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
-     -  ./claw_data:/home/node/.openclaw:rw
-     -  # Your config file
+     - ./claw_data:/home/node/.openclaw:rw
+     - # Your config file
+     - ./workspace:/home/node/.openclaw/workspace:rw
    environment:
      - FILE_SERVER_HOST=0.0.0.0
      - FILE_SERVER_PORT=8080

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-syncralis",
   "name": "openclaw-syncralis",
   "displayName": "Syncralis Gateway",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "An industry-grade file sharing, secure download, and load-balanced gateway designed for high-availability OpenClaw environments.",
   "type": "gateway",
   "main": "./server.js",
@@ -22,7 +22,10 @@
   },
   "configSchema": {
     "type": "object",
-    "required": [],
+    "required": [
+      "TAVILY_API_KEY",
+      "BRAVE_API_KEY"
+    ],
     "properties": {
       "FILE_SERVER_PORT": {
         "type": "number",
@@ -58,6 +61,16 @@
         "type": "string",
         "description": "Authentication token for the Ngrok service."
       },
+      "WORKSPACE_DIR": {
+        "type": "string",
+        "description": "Optional: Custom absolute path for the workspace volume. Leave blank to default to ~/.openclaw/workspace",
+        "default": ""
+      },
+      "NGROK_API_PORT": {
+        "type": "number",
+        "default": 4040,
+        "description": "Optional: The local port Ngrok uses for its API (used for auto-discovery). Default is 4040."
+      },
       "URL_SIGNING_SECRET": {
         "type": "string",
         "description": "Optional: 32-byte string for signing URLs."
@@ -66,14 +79,17 @@
     "additionalProperties": true
   },
   "env": {
-    "required": [],
-    "optional": [
+    "required": [
       "TAVILY_API_KEY",
-      "BRAVE_API_KEY",
+      "BRAVE_API_KEY"
+    ],
+    "optional": [
       "PUBLIC_TUNNEL_URL",
       "NGROK_AUTHTOKEN",
       "FILE_SERVER_HOST",
       "FILE_SERVER_PORT",
+      "WORKSPACE_DIR",
+      "NGROK_API_PORT",
       "URL_SIGNING_SECRET"
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-syncralis",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "An industry-grade file sharing, secure download, and load-balanced gateway designed for high-availability OpenClaw environments.",
   "type": "module",
   "main": "./server.js",
@@ -24,6 +24,14 @@
   ],
   "author": "PSLKK <coregravity0.0.0@protonmail.com> (https://pslkk.space)",
   "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pslkk/openclaw-syncralis.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pslkk/openclaw-syncralis/issues"
+  },
+  "homepage": "https://github.com/pslkk/openclaw-syncralis#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
@@ -56,7 +64,10 @@
     },
     "configSchema": {
       "type": "object",
-      "required": [],
+      "required": [
+        "TAVILY_API_KEY",
+        "BRAVE_API_KEY"
+      ],
       "properties": {
         "FILE_SERVER_PORT": {
           "type": "number",
@@ -92,6 +103,16 @@
           "type": "string",
           "description": "Authentication token for the Ngrok service."
         },
+        "WORKSPACE_DIR": {
+          "type": "string",
+          "description": "Optional: Custom absolute path for the workspace volume. Leave blank to default to ~/.openclaw/workspace",
+          "default": ""
+        },
+        "NGROK_API_PORT": {
+          "type": "number",
+          "default": 4040,
+          "description": "Optional: The local port Ngrok uses for its API (used for auto-discovery). Default is 4040."
+        },
         "URL_SIGNING_SECRET": {
           "type": "string",
           "description": "Optional: 32-byte string for signing URLs."
@@ -100,14 +121,17 @@
       "additionalProperties": true
     },
     "env": {
-      "required": [],
-      "optional": [
+      "required": [
         "TAVILY_API_KEY",
-        "BRAVE_API_KEY",
+        "BRAVE_API_KEY"
+      ],
+      "optional": [
         "PUBLIC_TUNNEL_URL",
         "NGROK_AUTHTOKEN",
         "FILE_SERVER_HOST",
         "FILE_SERVER_PORT",
+        "WORKSPACE_DIR",
+        "NGROK_API_PORT",
         "URL_SIGNING_SECRET"
       ]
     }

package/server.js

@@ -19,14 +19,50 @@ import crypto from 'crypto';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 dotenv.config({ path: path.resolve(__dirname, '.env') });
 
+let activeTunnelUrl = process.env.PUBLIC_TUNNEL_URL;
+if (!activeTunnelUrl) {
+  const ngrokApiPort = parseInt(process.env.NGROK_API_PORT, 10) || 4040;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 2000);
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${ngrokApiPort}/api/tunnels`, {
+      signal: controller.signal
+    });
+        
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      const data = await response.json();
+      if (Array.isArray(data?.tunnels)) {
+        const httpsTunnel = data.tunnels.find(t => 
+          typeof t.public_url === 'string' && t.public_url.startsWith('https://')
+        );
+        if (httpsTunnel) {
+          activeTunnelUrl = httpsTunnel.public_url;
+          console.log(`\n\x1b[32m[System]\x1b[0m Auto-discovered active Ngrok tunnel: ${activeTunnelUrl}\n`);
+        }
+      }
+    }
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error.name === 'AbortError') {
+      console.error(`\n\x1b[33m[Warning]\x1b[0m Ngrok auto-discovery timed out on port ${ngrokApiPort}.`);
+    } else {
+      console.error(`\n\x1b[33m[Warning]\x1b[0m PUBLIC_TUNNEL_URL is empty and local Ngrok was not detected.`);
+    }
+    console.error(`External download links will fail. Operating in Local-Only Mode.\n`);
+  }
+}
+
 const GATEWAY_CONFIG = {
   host: process.env.FILE_SERVER_HOST || '127.0.0.1',
   port: parseInt(process.env.FILE_SERVER_PORT, 10) || 8080,
   //workspace: path.join(os.homedir(), '.openclaw', 'workspace'),
   tavilyKey: process.env.TAVILY_API_KEY,
   braveKey: process.env.BRAVE_API_KEY,
-  tunnelUrl: process.env.PUBLIC_TUNNEL_URL,
-  ngrokToken: process.env.NGROK_AUTHTOKEN,
+  tunnelUrl: activeTunnelUrl,
+  //ngrokToken: process.env.NGROK_AUTHTOKEN,
   signingSecret: process.env.URL_SIGNING_SECRET || crypto.randomBytes(32).toString('hex')
 };
 
@@ -36,13 +72,20 @@ let requestCount = 0;
 
 const require = createRequire(import.meta.url);
 const pdf = require("pdf-parse");
+const pkg = require("./package.json");
+
+// Check for version flags before starting the server
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  console.log(`openclaw-syncralis v${pkg.version}`);
+  process.exit(0);
+}
 
-const WORKSPACE_DIR = path.join(os.homedir(), '.openclaw', 'workspace');
+const WORKSPACE_DIR = process.env.WORKSPACE_DIR || path.join(os.homedir(), '.openclaw', 'workspace');
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024;
 
 function generateSignedUrl(filename, expirationMinutes = 60) {
     if (!GATEWAY_CONFIG.tunnelUrl) {
-        throw new Error("PUBLIC_TUNNEL_URL is not configured.");
+      throw new Error("PUBLIC_TUNNEL_URL is not configured.");
     }
     
     const safeFilename = path.basename(filename);
@@ -72,7 +115,7 @@ async function getSecurePath(requestedPath) {
 }
 
 const server = new Server(
-    { name: "openclaw-syncralis", version: "2.1.0" },
+    { name: "openclaw-syncralis", version: "2.2.0" },
     { capabilities: { tools: {} } }
 );
 
@@ -424,7 +467,7 @@ async function main() {
         startSecureFileServer();
         const transport = new StdioServerTransport();
         await server.connect(transport);
-        console.error("[System] OpenClaw Enterprise File Ops MCP running securely via stdio");
+        console.error("[System] openclaw-syncralis MCP running securely");
     } catch (error) {
         console.error("[Fatal] Server connection failed:", error);
         process.exit(1);