Universal network scanner bridge
Scan from any network scanner to your computer, NAS, Paperless-NGX, or Home Assistant.
OpenScanHub connects your network scanner to wherever you want your documents to go. It supports multiple scanner protocols, auto-discovery, automatic document feeder monitoring, and a simple web-based setup wizard that anyone can use - no technical skills required.
Built by Parallax Intelligence Partnership, LLC and released as free, open-source software.
parallaxintelligence.ai | parallaxintelligence.online | GitHub
Most network scanners can scan - but getting those scans where you actually need them is the hard part. OpenScanHub solves this:
- Your scanner talks eSCL, WSD, FTP, or saves to a folder
- OpenScanHub catches the scan and routes it
- Your documents land in your folder, NAS, Paperless-NGX, or trigger a Home Assistant automation
No drivers to install. No vendor apps. One setup wizard and you're done.
- Four scanner protocols - eSCL (AirScan/AirPrint), WSD (Web Services for Devices), FTP receiver, and folder watching
- Scan-to-FTP replacement - Built-in FTP server receives scans pushed from your scanner's control panel
- Auto-discovery - Finds compatible scanners on your network automatically
- Paperless-NGX - Direct API upload or consume folder drop
- Home Assistant - REST commands for scan buttons on your HA dashboard
- ADF auto-scan - Automatically scans when paper is placed in the document feeder
- Folder watcher - Route files from any scanner that saves to a network share
- Web UI - Setup wizard + scan dashboard, works on phone and desktop
- Three deployment options - Windows EXE, Docker, or pip install
- Download
OpenScanHub.exefrom the latest release - Double-click to run
- Your browser opens to the setup wizard
- Follow the 6 steps to configure your scanner
The app runs in your system tray. Right-click for quick scan options.
git clone https://github.com/parallaxintelligencepartnership/openscan-hub.git
cd openscan-hub
docker compose up -dOpen http://your-server:8020 in your browser to run the setup wizard.
Note:
network_mode: hostis required for mDNS scanner auto-discovery. If you configure your scanner IP manually, you can use standard port mapping instead.
pip install openscan-hub
openscanOpen http://localhost:8020 in your browser.
| Protocol | Scanners | How It Works |
|---|---|---|
| eSCL (AirScan) | HP, Canon, Epson, Brother, and most printers made after ~2015 | OpenScanHub pulls scans via HTTP. Auto-discovered via mDNS. |
| WSD | Xerox, Ricoh, and enterprise MFPs | OpenScanHub pulls scans via SOAP. Auto-discovered via WS-Discovery. |
| FTP Receiver | Any scanner with "Scan to FTP" | Scanner pushes to OpenScanHub's built-in FTP server. Drop-in replacement for a standalone FTP server. |
| Folder Watch | Any scanner that saves to a network share | OpenScanHub watches a folder and routes new files automatically. |
Don't see your scanner? If it's on your network and less than 10 years old, it almost certainly supports eSCL or Scan-to-FTP. Try the auto-discovery first, or set up the FTP receiver.
OpenScanHub exposes a simple REST API that makes it easy to add Scan buttons to your Home Assistant dashboard.
Add the following to your Home Assistant configuration.yaml (replace OPENSCAN_IP with the IP/hostname where OpenScanHub is running):
rest_command:
openscan_adf:
url: "http://OPENSCAN_IP:8020/api/scan/adf"
method: GET
timeout: 120
openscan_flatbed:
url: "http://OPENSCAN_IP:8020/api/scan/flatbed"
method: GET
timeout: 120
openscan_status:
url: "http://OPENSCAN_IP:8020/api/status"
method: GETGo to Developer Tools > YAML > Check Configuration, then restart.
Add cards to your HA dashboard. Here's a simple example using the Button card:
type: horizontal-stack
cards:
- type: button
name: Scan (Feeder)
icon: mdi:file-document-arrow-right
tap_action:
action: perform-action
perform_action: rest_command.openscan_adf
hold_action:
action: url
url_path: http://OPENSCAN_IP:8020/dashboard
- type: button
name: Scan (Flatbed)
icon: mdi:scanner
tap_action:
action: perform-action
perform_action: rest_command.openscan_flatbed
hold_action:
action: url
url_path: http://OPENSCAN_IP:8020/dashboardTip: Long-press either button to open the full OpenScanHub dashboard in your browser.
You can also trigger scans from HA automations:
automation:
- alias: "Morning Document Scan"
trigger:
- platform: time
at: "08:00:00"
action:
- action: rest_command.openscan_adfIf your scanner supports "Scan to FTP" (most enterprise MFPs do), OpenScanHub can completely replace your FTP server. Instead of setting up vsftpd or FileZilla Server, just point your scanner at OpenScanHub.
On your scanner's control panel or web admin, configure the FTP scan destination:
| Setting | Value |
|---|---|
| Server/Host | IP address of the machine running OpenScanHub |
| Port | 2121 (default, configurable) |
| Username | scan (default, configurable) |
| Password | scan (default, configurable) |
| Path/Directory | / |
| File Format | PDF (recommended) or JPEG/TIFF |
That's it. When someone presses "Scan" on the physical scanner and selects the FTP destination, the file lands in OpenScanHub and gets routed to your output folder, Paperless-NGX, or wherever you've configured.
If running in Docker, expose the FTP ports:
ports:
- "8020:8020" # Web UI
- "2121:2121" # FTP control
- "60000-60100:60000-60100" # FTP passive dataOpenScanHub supports two methods of sending scans to Paperless-NGX:
| Method | Best For | Setup |
|---|---|---|
| Consume Folder | Paperless on the same machine or NAS | Point to your Paperless consume directory |
| REST API | Remote Paperless instances | Enter URL + API token in the wizard |
Both methods are configured during the setup wizard. You can also enable both for redundancy.
Config is stored at:
| Platform | Path |
|---|---|
| Windows | %APPDATA%\OpenScanHub\config.json |
| Docker | /config/openscan.json |
| Linux/Mac | ~/.config/openscan/config.json |
Override with the OPENSCAN_CONFIG_DIR environment variable.
openscan [options]
--port PORT Web UI port (default: 8020)
--no-browser Don't auto-open browser on startup
--log-level LEVEL DEBUG, INFO, WARNING, or ERROR
--version Show version and exit
pip install -e ".[tray,dev]"
python build_exe.py
# Output: dist/OpenScanHub.exedocker build -t openscan-hub .openscan/
scanner/
base.py # Abstract scanner protocol interface
escl.py # eSCL (AirScan) implementation
wsd.py # WSD implementation
ftp_receive.py # FTP receiver (Scan-to-FTP replacement)
folder_watch.py # Folder watcher implementation
web/
server.py # HTTP server + routing
wizard_api.py # Setup wizard API endpoints
dashboard_api.py # Dashboard API endpoints
static/ # HTML, CSS, JS (vanilla, no frameworks)
config.py # JSON config management
discovery.py # Unified scanner discovery
output.py # Output handlers (file save, Paperless)
monitor.py # ADF state monitor (auto-scan)
main.py # CLI entry point
tray.py # Windows system tray (pystray)
| Package | License | Purpose | Required |
|---|---|---|---|
| zeroconf | Apache 2.0 | mDNS scanner discovery | Yes |
| pyftpdlib | MIT | Built-in FTP server for Scan-to-FTP | Yes |
| pystray | LGPL v3 | Windows system tray icon | Windows EXE only |
| Pillow | HPND | Tray icon rendering | Windows EXE only |
Everything else is Python standard library. No JavaScript frameworks. No build tools. Just Python.
Contributions are welcome! Please open an issue first to discuss what you'd like to change.
MIT - Copyright (c) 2025 Parallax Intelligence Partnership, LLC