Download NowVersion 2.18.3
FilePulseVersion 2.18.3
Download Now

FilePulse User Guide

Complete Tutorial and Reference

Learn how to use FilePulse effectively with our comprehensive guide covering basic operations to advanced configurations.

Getting Started

How to run FilePulse for the first time

FilePulse runs on Windows, macOS, and Linux. The local web console uses ports 80 (HTTP) and 443 (HTTPS) by default. If either port is already in use, FilePulse normally finds an available HTTP/HTTPS port pair between 80 and 10000, writes the new ports to config.json, and restarts automatically. The startup notice shows the new access address. Edit config.json manually only when automatic selection or saving fails, or when your network requires fixed ports.

Platform guide

Windows

Run FilePulse.exe from its own folder. FilePulse can elevate automatically when indexing, file operations, or low-port binding requires administrator access.

Windows Package Instructions

1. Extract to a separate folder

Extract the complete package into its own folder before running it. For an upgrade, use a new folder so older configuration and runtime files do not conflict with the new version.

2. Start FilePulse

Double-click FilePulse.exe to start it. Do not force “Run this program as administrator” in the Compatibility tab; the normal launcher manages elevation while preserving normal-permission file opening.

FilePulse.exe
3. Check the shield overlay

If FilePulse.exe displays a shield icon after download, please move it to another folder until the shield disappears, otherwise it will affect opening a target with normal permissions. You can ignore this if you don't need this feature.

4. Handle an unavailable volume

If "Volume change log is inactive" appears, it means there is a problem with a drive letter. You need to modify config.json to remove the problematic drive letter from drive_list.

Platform guide

macOS

macOS Gatekeeper may block apps downloaded from the internet. Please refer to the steps below based on your version:

.app Bundle Instructions

Recommendation: Move the app to another directory (e.g., /Applications) after downloading. Do not run it directly from the Downloads folder to avoid system blocks.

1. Remove quarantine attribute

Open Terminal in the app directory and run:

xattr -dr com.apple.quarantine FilePulse.appchmod +x FilePulse.app/Contents/MacOS/*
2. Allow in System Settings

If blocked: Open "System Settings" → "Privacy & Security" → Scroll to the bottom → Find FilePulse and click "Open Anyway".

Standard Version Instructions

1. Grant execution permissions

Open Terminal in the app directory and run:

chmod +x FilePulse
2. Allow in System Settings

If blocked: Open "System Settings" → "Privacy & Security" → Click "Open Anyway".

3. Run with sudo

Run with sudo to ensure full functionality (including tray icon):

sudo ./FilePulse
4. Run in background with sudo

Use the following script to run in background (you need to enter your sudo password each time you run it):

View the complete background startup script on the download page
  • Optional: To include macOS-protected folders such as Desktop, Documents, and Downloads in search, go to System Settings -> Privacy & Security -> Full Disk Access, then add and enable the app that launches FilePulse, either Terminal.app or FilePulse.app. FilePulse can still run without this permission, but files in those folders may not appear in search results.

Platform guide

Linux

FilePulse has been tested on Debian, Ubuntu, Arch Linux, and CachyOS, and works normally overall.

AppImage Instructions

1. Grant execution permission

After extracting the zip, open Terminal in the folder containing the AppImage file and run:

chmod +x ./FilePulse.AppImage
2. Launch AppImage

If there is only one AppImage file in the current directory, you can start it directly with:

sudo ./FilePulse.AppImage

Standard Version Instructions

1. Grant execution permissions

Open Terminal in the app directory and run:

chmod +x FilePulse
2. Install dependencies

Run the following command in Terminal (Ubuntu/Debian):

sudo apt install -y libxdo3 libunwind-15 libayatana-appindicator3-1 libwebkit2gtk-4.1-0
3. Run with sudo

It is recommended to start the application with root privileges to ensure all features work correctly:

sudo ./FilePulse
4. Run in background with sudo

You can use the following script to start FilePulse with sudo and run it in the background without waiting. You need to enter your sudo password each time you run it:

View the complete background startup script on the download page
  • If you are using X11, both the AppImage and standard builds work normally, and all features are fully supported.
  • If you are using Wayland, we recommend the standard build. AppImage can still be used on Wayland, but due to known Wayland-side issues, double-click launching or enabling auto-start may cause the UI or startup process to hang. If you still prefer the AppImage build, do not launch it by double-clicking and do not enable auto-start. Instead, start it with: sudo ./FilePulse.AppImage

Default ports: 80 (HTTP) and 443 (HTTPS)

When a default port is occupied, FilePulse normally selects available ports, saves them to config.json, and restarts automatically. Use manual configuration only for fixed-port requirements or if automatic recovery fails.

Free Trial

30-day free trial for new users

Important Notes

If FilePulse.exe displays a shield icon after download, please move it to another folder until the shield disappears, otherwise it will affect opening a target with normal permissions. You can ignore this if you don't need this feature.

If running normally, the program will automatically switch to administrator privileges, but please do not set "Run this program as administrator" in the compatibility tab of FilePulse.exe properties. If compatibility is set, it will have the same issue as mentioned above and cannot open a target with normal permissions. You can ignore this if you don't need this feature.

If "Volume change log is inactive" appears, it means there is a problem with a drive letter. You need to modify config.json to remove the problematic drive letter from drive_list.

After version upgrade, it is recommended to place the newly downloaded FilePulse in a separate new folder to avoid conflicts between old and new configurations.

On Windows, macOS, and Linux, the operating system’s file-event queue has a finite capacity. If a large number of files are changed in a very short time—for example, deleting 10,000 files within one second—some events may not reach FilePulse, causing file information to be temporarily missed. This is an operating-system limitation rather than a FilePulse fault. Restart FilePulse to resynchronize.

Core Features Overview

Explore the main capabilities of FilePulse

Core Feature 1: File Name Search

Similar to Everything, with various complex filtering conditions, mainly used for users' complex searches, can respond in milliseconds

Core Feature 2: File Content Search

Search inside text, Office documents, PDFs, books, web pages, and image-based content with OCR. Text inside screenshots, scanned PDFs, and embedded document images can become searchable after indexing.

Core Feature 3: Visual Search

Use an image, screenshot, or video as the query to find visually similar images and matching video segments, then review thumbnails, paths, servers, and target time ranges.

Core Feature 4: Quick Launcher

Similar to Listary, input keywords and results are pre-sorted according to most habits, quickly locate target location and launch

Core Feature 5: File Deduplication

Compare files by size and signatures to locate duplicates quickly, review results safely, and clean up storage efficiently.

Core Feature 6: Remote Preview & Transfer

Remote quick preview for documents, books, archives, images, audio, and video, plus download, upload, and remote file location.

Core Feature 7: Folder Auto Remote Sync

Continuously sync mapped local and remote folders with periodic updates, reconnect resilience, and clear deletion tracking.

Core Feature 8: AI Conversations

Manage LLM options, keep persistent multi-session history, support image upload, and clear all sessions in one click.

Core Feature 9: Launcher Panel

Similar to Sonic Launcher, pre-add commonly used software (due to browser limitations, drag and drop cannot get complete paths, currently requires manual input, future native app will support drag and drop)

Core Feature 10: Cluster Networking

Uses the core search and remote capabilities; the launcher panel is optional in cluster mode.

Core Feature 11: Context Search

Auto-fill the current file manager path with a shortcut across Windows, macOS, and Linux, continue from supported open dialogs on Windows, and refine or step up the active search scope when needed.

Core Feature 12: Search Workspace

Manage ongoing search tasks with persistent annotations, grouping, pinned items, custom sorting, startup restoration, and smoother keyboard navigation.

Workflow Guide

Choose a task, then open the matching step-by-step use case.

1

File Name Search

Use filters, regex, and pinyin matching to locate targets instantly.

Open step-by-step case
2

File Content Search

Search across document text and OCR-recognized image text with indexing, scoring, highlights, and quick preview.

Open step-by-step case
3

Visual Search

Upload an image or video, or paste a screenshot, to find similar images and jump to matching video segments.

Open step-by-step case
4

Quick Launcher

Open apps and folders fast with habit-based sorting.

Open step-by-step case
5

File Deduplication

Find redundant files and keep only the versions you need.

Open step-by-step case
6

Remote Transfer

Upload, download, and locate files across nodes with smooth remote access.

Open step-by-step case
7

Folder Auto Remote Sync

Keep mapped folders between local and remote nodes continuously synchronized with automatic updates.

Open step-by-step case
8

Quick Preview

Instantly preview documents, images, and media without leaving the workflow.

Open step-by-step case
9

AI Conversations

Continue work through contextual AI chats with image upload and persistent session history.

Open step-by-step case
10

Sharing

Share selected content with controlled access when collaboration is needed.

Open step-by-step case
11

Context Search

Start from the current folder faster, then manually refine the scope or jump to the parent scope as the search expands.

Open step-by-step case
12

Search Workspace

Use persistent annotations, grouping, pinned items, custom sorting, and smoother result navigation to keep complex searches under control.

Open step-by-step case

Improve Search Efficiency

These focused tools help you return to queries, keep parallel tasks organized, and review results faster.

Search History

Reuse recent queries without rebuilding the same search.

Where: Search, Content Search, or Quick Launcher → history button beside the query box.

View use case

Search Presets

Save a complete set of search conditions, reuse it later, or make it the default.

Where: Search and Content Search → Search Presets.

View use case

Multi-tab Workspace

Keep multiple search, content search, visual search, or launcher tasks open at once.

Where: The tab bar at the top of supported search pages.

View use case

Export Results

Export the current filtered result set as a TSV file for further processing.

Where: Result footer → Export.

View use case

Icon View

Browse with thumbnails and adjust the icon size to scan visual results faster.

Where: Result footer → Display Settings → View mode.

View use case

Search Annotations

Group, pin, and custom-sort results that need continued attention.

Where: Settings → Search Experience, then the result context menu or annotation manager.

View use case

Supported File Content Search Types

FilePulse supports content searching across multiple file formats

Different file types are processed by specialized handlers, including OCR handlers for images, scanned PDFs, and pictures embedded in Office documents. Choose handlers by file type in Settings -> Content Rules / Handler Profiles.

Standard Text Extraction

Use these handlers when the document already contains selectable text, structured document text, book content, or web page text.

text_handler

Reads all text-type files as is

txt, md, json, py, js, css, xml, csv, log, etc.

docx_handler

All text content from Microsoft Word documents

docx

xlsx_handler

All text content from Microsoft Excel spreadsheets

xlsx

pptx_handler

All text content from Microsoft PowerPoint presentations

pptx

pdf_handler

All text content from PDF documents

pdf

rtf_handler

All text content from Rich Text Format documents

rtf

epub_handler

Searchable content from EPUB book files

epub

fb2_handler

Searchable content from FB2 book files

fb2

html_handler

HTML web page content with tags removed

html, htm

OCR Enhanced Recognition

Use these handlers when important information appears inside screenshots, photos, scanned pages, image-heavy PDFs, or images embedded in Office documents.

docx_ocr_handler

Word document text plus OCR-recognized text from embedded images

docx with screenshots, photos, or scanned pages

xlsx_ocr_handler

Excel spreadsheet text plus OCR-recognized text from embedded images

xlsx with pasted screenshots or image notes

pptx_ocr_handler

PowerPoint slide text plus OCR-recognized text from images in slides

pptx with screenshots, diagrams, or photo slides

pdf_ocr_handler

PDF text plus OCR-recognized text from scanned pages and embedded images

pdf with scans, screenshots, or mixed text and images

image_ocr_handler

OCR-recognized text from image files so screenshots and photos can be found by content

png, jpg, jpeg, webp, bmp, tiff

Visual Search Media

Use these file types when images or videos should be available for visual search, screenshot matching, and video segment review. Video visual search requires FFmpeg to be available.

visual_search

Images and common video files can be used as visual search targets or query files. Image search works directly; video indexing and querying require FFmpeg.

jpg, jpeg, png, webp, bmp, tiff, mp4, mov, mkv, avi, webm

Tip: use OCR handlers when searchable information is stored as an image rather than selectable text.

Keyboard Shortcuts

Master these shortcuts to boost your productivity

Global Shortcuts

Alt + Q
Search within the currently open folder or dialog, with the option to adjust the active scope afterward.
Alt + F
Open quick launcher, input some keywords to immediately run a program
Alt + W
Open launcher panel, users can add some path icons, future can open by double-clicking
Alt + `
Open the file name search page. It can auto-fill the current file manager path on Windows, macOS, and Linux, continue from supported Windows dialogs, and let you refine the scope.
Win + `
Open file content search page

Web Interface Shortcuts

Alt + 4
In search and quick launcher pages, quickly modify search type (folders and files, folders, files)
Alt + 1/2
In launcher panel, used to quickly switch groups
Alt + 1/2/3
Switch Content Plugin
Alt + Page Up/Down, Ctrl + Arrow Keys
Switch pagination
Up/Down Arrow Keys
Select items in search results table
Left/Right Arrow Keys
Open menu for selected item, fast forward/rewind video by 5 seconds in preview
Enter
Execute menu item
Ctrl + Enter
Quickly locate target location in File Explorer
Ctrl + C
Copy target file
Ctrl + X
Cut target file
Space
Quick preview selected file remotely
Alt + Enter
Fullscreen display for preview video window
Ctrl + Left/Right Arrow Keys
Fast forward/rewind video by 30 seconds in preview window
Ctrl + Alt + Left/Right Arrow Keys
Switch between tabs
Alt + /
Select search content on the page

Advanced Usage

Unlock the full potential of FilePulse

Certificate Replacement

The built-in certificate is a development certificate. To replace with a real certificate, replace the files in the certs directory.

Enable HTTP3

HTTP2/HTTP3 are enabled by default, but may automatically downgrade to HTTP2 due to development certificate issues. After replacing with a real certificate, HTTP3 can be used normally.

Advanced Expressions

Simple Expression (Advanced expression OFF)

Search Content and Path edit boxes support NOT (!), AND (space), OR (

Advanced Expression (Advanced expression ON)

Search Content and Path edit boxes support NOT <not>, AND <and>, OR <or>, left parenthesis <left>, right parenthesis <right>

Advanced File Content Search

Normal Search (Linear Search OFF)

Four search modes: normal mode, regular expression, prefix matching, fuzzy matching. Fuzzy matching has the worst performance, try to avoid using it. Prefix matching requires at least two word segments to start, and in simple expressions it is separated by spaces, so prefix matching needs advanced expressions.

Linear Search (Linear Search ON)

Two search modes: wildcard search, regular expression search. Both perform individual matching on all files to be queried, performance will be worse.

Connect to Remote Server

Add the address, protocol, username, and password under Settings → Remote Servers. Successfully saved servers persist across restarts; FilePulse reconnects automatically after startup and retries failed connections with increasing delays. Use the connection status in Settings to confirm whether a server is currently online.

Remote Drive Mounting

1

Configure and select a saved, online server, then confirm the callback protocol and address that the remote instance can reach.

2

Enable automatic mounting to retain the mount configuration across restarts. The first mount can take longer when the remote server contains many files.

3

FilePulse checks the remote instance, callback health, and mount lease. If the instance restarts, disconnects, or the mount becomes stale, FilePulse clears stale remote data and attempts to mount again; remote results may be temporarily unavailable during recovery.

Windows WebDAV Guide

When mounting a WebDAV service in Windows, note the following settings for HTTP access and file size limits.

Enable HTTP
1

Press Win + R, enter regedit, and open Registry Editor.

2

Go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters.

3

Find BasicAuthLevel and set its value to 2.

4

Press Win + R, enter services.msc, and open Services.

5

Find WebClient and restart the service.

File size exceeds the limit
1

The default file size limit for Windows WebDAV transfers is 50 MB.

2

In the same registry path, find FileSizeLimitInBytes.

3

Change the default value 2faf080 to ffffffff to raise the maximum transferable size from 50 MB to 4 GB.

4

Restart the WebClient service.

Windows Share Mapping

Before using sharing on Windows, enable WebClient basic authentication in the registry.

1

Right-click Start and choose Run.

2

Type regedit and click OK.

3

In Registry Editor, navigate to HKEY_LOCAL_MACHINE > SYSTEM > CurrentControlSet > Services > WebClient > Parameters.

4

Open BasicAuthLevel and set Value data to 2.

5

Restart the computer and use sharing again.

Settings, Updates & Migration

Use the Settings page to export or import configuration, check for built-in updates, and migrate search workspace, sharing, sync, LLM, content rule, and remote server data.

Open downloads and release packages

Developer API

Connect AI agents, scripts, launchers, and internal tools to FilePulse search, preview, and download capabilities through the authenticated local HTTP API.

Read the developer API guide

config.json Configuration Reference

config.json controls the local service identity, login, ports, indexed locations, shortcuts, startup behavior, and a few runtime preferences. Most users only need to adjust ports, drive_list, hot_keys, instance policy, or startup options when the default environment is not suitable.

Editing recommendations

Ports, drive_list, hot_keys, multi-instance policy, and startup options are reasonable fields to adjust manually. Account credentials should be changed from the web interface whenever possible. Restart FilePulse after changing ports, monitored locations, hotkeys, or max_batch so the new behavior can be applied consistently.

server_name

Display name of the local FilePulse node. Keep it unique when you use remote nodes or cluster workflows.

port_http / port_https

HTTP and HTTPS ports used by the local web console and service APIs. If ports 80 or 443 are occupied, change these values before startup and visit the matching address.

drive_list

Locations FilePulse monitors and indexes. On Windows this is usually drive letters, while macOS and Linux use paths such as /Users or /home.

hot_keys

Global shortcut definitions for current folder search, content search, quick launcher, launcher panel, and context search.

open_link_after_boot

Controls whether FilePulse opens the browser automatically after startup. Disable it for background startup or server deployments.

max_batch

Batch size for content indexing. Larger values may build faster but require more memory and CPU. Lower it if content indexing cannot allocate memory.

ffmpeg_max_parallelism

Optional cap for concurrent FFmpeg work used by video visual search and previews. Leave it null for automatic selection; lower it when media indexing causes high CPU or memory pressure.

ocr_max_parallelism

Optional cap for concurrent OCR extraction. Leave it null for automatic selection; lower it on machines with limited CPU or memory.

hide_console_on_startup

Controls whether the console window is hidden when FilePulse starts in environments that support it.

native_log_enabled

Controls native-side logging behavior for troubleshooting startup, shortcut, or desktop integration issues.

instance_policy.allow_multi_filepulse

Controls whether multiple FilePulse service instances can run at the same time.

instance_policy.allow_multi_native

Controls whether multiple native desktop helper instances can run at the same time.

boot_root_autostart_enabled

Controls startup registration. Use it when you want FilePulse to start automatically after login or boot.

password / last_password_change / saved_system_password

Sensitive or system-managed fields. Do not edit them manually; change the account password and system-password storage through the FilePulse Settings interface.

Settings import/export can migrate config.json together with sharing, sync, LLM, content rules, remote server, and search workspace data. This guide only explains config.json because the other files are better managed from the web interface.

Troubleshooting

If FilePulse closes itself after the machine resumes from sleep or a similar state, this is usually not a program defect. It happens because FilePulse's online verification is interrupted when the terminal enters sleep or a similar state, so the program exits automatically. Simply restart FilePulse.

If memory cannot be allocated when building search content, max_batch is set too large. Just modify the config.json file and set max_batch to a smaller value, then run again.

If search content build gets stuck, you can delete all entries in rules in rules.json, which is equivalent to clearing all rules, then run again.

Build results are in the index directory, which can be deleted at any time to rebuild. I personally recommend not building overly large plain text, such as a 500MB Word document with mostly images will be fine, but if it is a 500MB plain text file with pure text content, the search system may take a very long time to build. And such large plain text files will consume huge amounts of memory during building.