openclaw-syncralis

An industry-grade MCP gateway providing three capabilities: (1) secure workspace file sharing with HMAC-signed time-limited download links via Ngrok tunnel, (2) authenticated URL-to-workspace file downloads with MIME validation, and (3) load-balanced web search across Tavily and Brave with circuit-breaker failover. Requires outbound internet access and an optional Ngrok tunnel for public download links.

@PSL_KK@pslkk

Install

openclaw plugins install clawhub:openclaw-syncralis

Syncralis 🌐⚙️

An industry-grade, highly secure Model Context Protocol (MCP) server.

Syncralis provides load-balanced web searching, secure file downloads, and secure external file sharing, built on a hardened, hybrid architecture.

Works with OpenClaw, Cursor, Claude Desktop, and any MCP client that can launch Node-based servers.

🚀 Key Features

*Stateless File Sharing: Securely generates public Ngrok download links for files inside your workspace with a maximum of 3 download attempts until expiry.

⚠️ SECURITY WARNING: Generating a download link creates a public tunnel. This makes the specific local workspace file accessible to anyone who possesses the link when you share that link. Ensure you understand this exposure boundary before sharing sensitive local files.

*Load-Balanced Web Search: Intelligently alternates between Tavily and Brave Search APIs to prevent rate-limiting and ensure high availability.

*Secure File Downloads: Downloads files directly to your workspace with strict MIME-type enforcement and streaming size limits to prevent DoS attacks.

*Path Boundary Enforcement: Cryptographically verifies all file requests to prevent directory traversal attacks outside the designated workspace.

🔑 Requirements & API Keys (Free Tiers)

Syncralis relies on three external services. Each of these providers offers a generous free tier for developers (subject to their respective Terms and Conditions):

*Ngrok: Provides the secure public tunnel for file downloads. Claim your free static domain at https://ngrok.com.

*Tavily API: Provides AI-optimized web search results. Get your API key at https://tavily.com.

*Brave Search API: Provides the fallback web search index. Get your API key at https://brave.com/search/api/.

📦 Installation

Install the package globally via your terminal:

bash


npm install -g openclaw-syncralis

# OR via Openclaw: openclaw plugins install clawhub:openclaw-syncralis

⚙️ Configuration & Deployment

Syncralis is designed as a hybrid tool. It works perfectly on your native operating system (Windows/Mac/Linux) or securely inside a Dockerized environment.

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):

When running OpenClaw natively on your host machine, Syncralis spins up a secure local HTTP server bound strictly to localhost.

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

Add the generated Ngrok URL to your OpenClaw configuration generally inside (/home/node/.openclaw/openclaw.json):

json


"mcp": {
  "servers": {
    "syncralis": {
      "command": "node",
      "args": [
        "/home/node/.openclaw/extensions/openclaw-syncralis/server.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "FILE_SERVER_HOST": "127.0.0.1",
        "WORKSPACE_DIR": "",
        "PUBLIC_TUNNEL_URL": "https://your-ngrok-url.ngrok-free.app",
        "NGROK_API_PORT": 4040,
        "TAVILY_API_KEY": "your_tavily_key",
        "BRAVE_API_KEY": "your_brave_key",
        "URL_SIGNING_SECRET": "your_custom_32_character_secret_here"
      }
    }
  }
},
"plugins": {
  "entries": {
    "openclaw-syncralis": {
      "enabled": true
    }
  }
}

Option 2: Docker Environment Setup (Recommended for Production):

OpenClaw often executes tools as ephemeral child processes. In a containerized setup, it is highly recommended to run openclaw alongside Ngrok to serve the workspace volume 24/7. This guarantees your download links remain active even after the MCP process shuts down.

Configure your openclaw.json generally inside (/home/node/.openclaw/openclaw.json):

json


"mcp": {
  "servers": {
    "syncralis": {
      "command": "node",
      "args": [
        "/home/node/.openclaw/extensions/openclaw-syncralis/server.js"
      ],
      "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,
        "TAVILY_API_KEY": "your_tavily_key",
        "BRAVE_API_KEY": "your_brave_key",
        "URL_SIGNING_SECRET": "your_custom_32_character_secret_here"
      }
    }
  }
},
"plugins": {
  "entries": {
    "openclaw-syncralis": {
      "enabled": true
    }
  }
}

🐳 Complete Docker Compose (Just an example only):

If you are running OpenClaw entirely inside Docker, here is a complete, production-ready docker-compose.yml template to get Syncralis and Ngrok running together seamlessly.

yaml


version: '3.8'

networks:
 mcp_network:
   driver: bridge

services:
 # Your main OpenClaw instance
 openclaw_gateway:
   image: ghcr.io/openclaw/openclaw:latest # Replace with your actual OpenClaw image or version
   container_name: openclaw_gateway
   restart: unless-stopped
   networks:
     - mcp_network
   ports:
     - "127.0.0.1:18789:18789"
   extra_hosts:
     - "host.docker.internal:host-gateway"
   volumes:
     - ./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
     - PUBLIC_TUNNEL_URL=https://<your-custom-domain>.ngrok-free.app
     - TAVILY_API_KEY=${TAVILY_API_KEY}
     - BRAVE_API_KEY=${BRAVE_API_KEY}
   deploy:
     resources:
       limits:
         cpus: '2.0' # Hard cap: Cannot exceed 2 CPU cores
         memory: 2G
       reservations:
         memory: 512M

   logging:
     driver: "json-file"
     options:
       max-size: "10m"
       max-file: "5"
       compress: "true"

   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost:18789"]
     interval: 30s
     timeout: 10s
     retries: 3
     start_period: 40s

 # The Ngrok tunnel pointing to Syncralis's internal file server

 ngrok_tunnel:

   image: ngrok/ngrok:latest
   container_name: ngrok_tunnel
   restart: unless-stopped
   ports:
     - "4040:4040"
   networks:
     - mcp_network
   command: http openclaw_gateway:8080 --url=https://<your-custom-domain>.ngrok-free.app --log=stdout
   environment:
     - NGROK_AUTHTOKEN=${NGROK_AUTHTOKEN}
   depends_on:
     openclaw_gateway:
       condition: service_healthy

🔐 Advanced Configuration (The .env Method):

If you prefer to maintain "Industry Grade" security and not keep your API keys exposed in your main openclaw.json file, you can securely configure the plugin using a standard .env file directly inside the extension's folder and remove the env block at mcp server configuration in openclaw.json.

💻 Native OpenClaw (Local / NPM Installation):

Navigate to the plugin's directory:

bash


cd ~/.openclaw/extensions/openclaw-syncralis

Create and open the .env file:
bash
```
nano .env
```

Add your API keys securely:

env


NODE_ENV=production
WORKSPACE_DIR=""
PUBLIC_TUNNEL_URL="https://your-domain.ngrok-free.app"
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

Save the file (Ctrl + O, Enter, Ctrl + X) and restart your OpenClaw instance.

🐳 Docker Environment:

Write your API keys directly into a new .env file using notepad:

env


NODE_ENV=production
WORKSPACE_DIR=""
PUBLIC_TUNNEL_URL="https://your-domain.ngrok-free.app"
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=0.0.0.0

Open a terminal session directly inside the gateway's plugin directory:

bash


docker cp "C:/path/to/your/.env" container_name:/home/node/.openclaw/extensions/openclaw-syncralis/.env

Restart your OpenClaw gateway to apply the secure variables:
bash
```
docker restart container_name
```

🛡️ Security Parameters

MAX_QUERY_LENGTH: Defaults to 2000 characters.
TIMEOUT_MS: Defaults to 10000ms (10 seconds) to prevent hung API calls.
MAX_DOWNLOAD_ATTEMPTS: Defaults to 3 attempts with same generated download link.
CONFIRM_TOKEN_TTL_MS: Defaults to 5 minutes and specifies the time window within which the user must verify and confirm the correct file to generate a secure download link.

Size Limits: Syncralis enforces a hard limit of 50MB for all file reads and downloads to prevent memory exhaustion.

🗑️ Uninstallation

If you need to remove the plugin, follow the instructions for your specific environment below.

💻 Native OpenClaw (Local / NPM Installation):

*The Standard Method:

bash


openclaw plugins uninstall openclaw-syncralis

*The "Hard Reset" (If the CLI fails):

bash


rm -rf ~/.openclaw/extensions/openclaw-syncralis

🐳 Docker Environment:

*The Standard Method:

bash


docker exec -it container_name openclaw plugins uninstall openclaw-syncralis

*The "Hard Reset" (If the CLI fails):

bash


docker exec -it container_name rm -rf /home/node/.openclaw/extensions/openclaw-syncralis

🧹 Final Cleanup (Both Environments):

After uninstalling via either method:

Open your openclaw.json file.
Delete the openclaw-syncralis blocks from both the "plugins" and "mcp" sections.
Restart your OpenClaw environment (or run docker restart container_name) for a perfectly clean boot.

💬 Usage Examples (Prompts)

Once connected, you can ask your OpenClaw agent to perform complex I/O tasks:

*"Search the web for the latest advancements in solid-state batteries using syncralis mcp tool."

*"Download the PDF from [URL] and save it as report.pdf using syncralis mcp tool."

*"Download Tesla Model Y pdf from genuine sources and save it as tesla_model_y.pdf using syncralis mcp tool."

*"Generate a mobile download link for report.pdf using syncralis mcp tool."

Built for resilient, secure agentic workflows.

openclaw-syncralis

Install

Syncralis 🌐⚙️

🚀 Key Features

🔑 Requirements & API Keys (Free Tiers)

📦 Installation

⚙️ Configuration & Deployment

The Workspace Directory (WORKSPACE_DIR):

Choose the deployment method that matches your OpenClaw setup below:

🛡️ Security Parameters

🗑️ Uninstallation

💬 Usage Examples (Prompts)

The Workspace Directory (`WORKSPACE_DIR`):