Open local files from the browser — zero dependencies, single file, no installation (double-click to deploy).

htmlFileAgent is a lightweight local file opener that allows web pages (HTML/JS running in a browser) to call local programs to open files of any type. It is designed for enterprise intranet systems, offline document management systems, and other scenarios where you need to open local files from the browser.

• 🚀 Zero Dependencies — Built with Node.js/Bun, compiled into a single EXE, no runtime environment required
• 🔒 Secure & Controllable — Whitelist/blacklist mechanism, executable files blocked by default to prevent malicious invocation
• 📁 Full Character Support — Perfectly handles Tibetan, Emoji, special symbols, super-long paths, and other complex filenames (no more rundll32 garbled text)
• 🛡️ Crash-Proof Armor — Global exception catching (uncaughtException), even if underlying calls are blocked or error out, the service stays alive
• 🌐 HTTP + HTTPS — Local service with built-in CORS support, callable directly from the browser
• ⚡ One-Click Deploy — Double-click the EXE to auto-deploy, import certificates, and configure startup
• 🗑️ One-Click Uninstall — Run with --uninstall to completely remove the service and certificates

Browser (HTML/JS)
    ↓ HTTP/HTTPS (localhost)
htmlFileAgent.exe (Node.js)
    ↓ Primary engine: explorer.exe (native wide characters, perfect for Tibetan/special symbols)
    ↓ Fallback engine: rundll32 url.dll,FileProtocolHandler (compatibility fallback)
System default handler (Word, Excel, PDF reader, Photoshop...)

Prerequisites: Install Bun (recommended, zero config) or Node.js ≥ 18.

# Bun (recommended)
bun build --compile src/htmlFileAgent.js --outfile dist/htmlFileAgent.exe

# Node.js + pkg (alternative)
npm install -g pkg
pkg src/htmlFileAgent.js --targets node18-win-x64 --output dist/htmlFileAgent.exe

Send htmlFileAgent.exe to the client and double-click to run. It will automatically:

• Copy itself to C:\htmlFileAgent\
• Generate a configuration file config.json
• Generate a self-signed HTTPS certificate
• Create a scheduled task (auto-start on boot)
• Start the local service

Open http://127.0.0.1:19000/ping in a browser. A JSON response containing "ok": true means deployment succeeded.

Open demo/htmlFileAgent-demo.html to experience the full probe, absolute path open, and relative path open features.

Probe service status.

{
  "ok": true,
  "service": "html-file-agent",
  "version": "1.3.0.0",
  "ports": { "http": 19000, "https": 19443 },
  "sources": ["default"],
  "mode": "whitelist",
  "allowAllExtensions": true
}

Open a file. Two calling methods are supported:

• source + relative path (recommended): tries each configured root in order
• Absolute path: ?path=D:\Docs\a.xlsx or ?path=\\Server\Share\b.pdf (requires roots: ["*"] or path in whitelist)

Successful response example (includes the engine actually used):

{
  "ok": true,
  "path": "\\\\Server\\Share\\subdir\\file.xlsx",
  "local": "\\\\Server\\Share\\subdir\\file.xlsx",
  "method": "explorer"
}

Check whether a file exists without triggering the open action.

Open the containing directory in Windows Explorer and select the file.

Open the containing directory in Windows Explorer (without selecting the file).

Clear downloaded cache files from HTTP-type sources.

Edit C:\htmlFileAgent\config.json:

{
  "ports": { "http": 19000, "https": 19443 },
  "mode": "whitelist",
  "sources": {
    "default": {
      "type": "local",
      "tryAll": true,
      "roots": ["*"]
    }
  },
  "allowedExtensions": [],
  "blockExecutables": true,
  "blockedExtensions": [
    ".exe", ".bat", ".cmd", ".com", ".scr", ".ps1",
    ".vbs", ".js", ".msi", ".dll", ".reg", ".lnk"
  ],
  "cacheDir": "C:\\htmlFileAgent\\cache",
  "cacheMaxAgeHours": 24,
  "downloadTimeoutMs": 120000,
  "allowedHosts": []
}

The config supports ${VAR} syntax to dynamically reference environment variables, making it easy to share one config across multiple devices:

{
  "sources": {
    "docs": {
      "type": "local",
      "roots": ["${USERPROFILE}\\Documents"]
    }
  }
}

// Probe local service
const ping = await fetch('http://127.0.0.1:19000/ping').then(r => r.json());
if (!ping.ok) {
  alert('Local service not started. Please double-click htmlFileAgent.exe first.');
}

// Open a file (recommended: specify source and relative path)
const result = await fetch(
  'http://127.0.0.1:19000/open?source=default&path=' +
  encodeURIComponent('docs\\report.pdf')
).then(r => r.json());

if (result.ok) {
  console.log('File sent to system handler:', result.path);
} else {
  console.error('Failed to open:', result.error);
}

Run in a command prompt with administrator privileges:

htmlFileAgent.exe --uninstall

Or remove manually:

1. Delete the scheduled task htmlFileAgent (taskschd.msc)
2. Kill the process and delete the directory C:\htmlFileAgent\
3. Remove the trusted root certificate CN=htmlFileAgent Local (certlm.msc → Trusted Root Certification Authorities)

htmlFileAgent/
├── src/
│   └── htmlFileAgent.js        # Backend source code (Node.js/Bun)
├── demo/
│   └── htmlFileAgent-demo.html # Frontend demo page
├── README.md
├── LICENSE
└── .gitignore

Q: Browser shows "htmlFileAgent not detected"?

• A: Confirm the service is running (http://127.0.0.1:19000/ping is accessible), and fully close and reopen the browser.

Q: HTTPS certificate warning?

• A: Self-signed certificates trigger browser warnings — this is normal. For production, use a proper certificate.

Q: How do I restrict which directories can be opened?

• A: Modify sources.default.roots in config.json, e.g. ["D:\\Docs", "\\\\fileserver\\share"].

Q: How do I restrict which file types can be opened?

• A: Modify allowedExtensions in config.json, e.g. [".pdf", ".docx", ".xlsx"].

Q: Clicking a file does nothing, browser reports TypeError: Failed to fetch?

• A: This means the local service process has crashed. v1.2.0+ includes global uncaughtException handling and should not crash under normal conditions. Check if antivirus software blocked htmlFileAgent.exe (add it to the whitelist).

Q: HTTPS page blocked from calling HTTP endpoints?

• A: 127.0.0.1 is a local secure context and browsers allow it by default. If blocked, a system proxy (e.g. Clash/V2Ray) is likely configured — add 127.0.0.1 to the proxy bypass list.

v1.4.0 (Latest)

• Fixed: Wildcard root matching — roots: ["path\\*"] now also matches the root directory itself, not only its subdirectories.
• Improved: SERVICE_VER unified with exe file version for consistent version identification.

v1.3.2

• Improved: /reveal command parameter handling (merged /select, and path into a single argument for UNC/Chinese path compatibility).

v1.3.0

• New: /open-folder endpoint (open containing folder without selecting the file).
• Improved: /reveal command parameter handling (merged /select, and path into a single argument for UNC/Chinese path compatibility).

v1.2.0

• New: Primary engine switched to explorer.exe, perfectly supporting Cyrillic, Tibetan, special symbols, and super-long paths.
• New: Global crash-proof mechanism (uncaughtException catch) to eliminate TypeError: Failed to fetch caused by underlying call failures.
• Improved: Async response concurrency lock to prevent duplicate-response crashes in Node.
• Improved: Added rundll32 fallback for high availability in extreme environments.

v1.1.0

• New: Multi-source configuration with roots mechanism, supporting automatic addressing across multiple servers.
• New: Dynamic hot-reloading of config.json — no restart needed to change configuration.
• New: Independent /exists and /reveal endpoints.
• Improved: Removed default extension restrictions; executables blacklisted by default for better security.

v1.0.0

• Initial release: LAN file opener based on rundll32.

MIT © 2026 FatFatYoung

FatFatYoung — github.com/FatFatYoung