User guide

Installation

Choose the matching asset on the download page and verify it against SHA256SUMS before opening it. This guide describes delivery for 1.0; example URLs do not approve a build. Minimum 4 GB RAM; an SSD and 8–16 GB RAM are recommended for larger crawls.

macOS: DMG and first launch

Requires macOS 13 or later: one universal DMG for Apple silicon and Intel. Open the DMG, drag OpenSpider to Applications, eject the DMG and launch from Applications. The CLI is at /Applications/OpenSpider.app/Contents/MacOS/openspider.

For a signed, notarized release, Gatekeeper may ask you to confirm opening an app downloaded from the internet. Check the source and displayed developer. If the app is reported damaged, the developer is unknown or the signature cannot be verified, report the build instead of disabling protection. Approved release builds must pass this check.

Windows: NSIS, MSI and SmartScreen

Requires Windows 10 1809+ or Windows 11 x64; Windows on ARM runs x64 under emulation. EXE/NSIS installs for the current user without administrator rights; MSI installs per machine with administrator rights. Both include openspider.exe. They check WebView2 and download it if needed, requiring internet access. Open a new terminal to pick up PATH changes.

Signed release builds use Azure Artifact Signing. SmartScreen may still warn while reputation is low. Select “More info”, check the verified publisher and compare it with the approved release information. A reputation warning alone does not mean the signature is invalid. Stop and report an unknown publisher or invalid signature. The verified publisher will be listed here with the first signed release.

Silent installation examples for downloaded files: substitute the actual asset names. Run MSI in an elevated command prompt. For NSIS, /D must be last, without quotes even when the path contains spaces.

OpenSpider-setup.exe /S /D=C:\Tools\OpenSpider
msiexec /i OpenSpider.msi /qn /norestart INSTALLDIR="C:\Program Files\OpenSpider" ADDTOPATH=1

NSIS adds the user PATH entry. MSI adds the machine PATH entry on first installation with ADDTOPATH=1; upgrades retain the existing choice.

Homebrew and winget: planned

The Homebrew cask and winget distribution are planned and are not available yet. Use the DMG or Windows installer for now; no package-manager command is approved here.

JavaScript rendering and Chromium

Chromium is not bundled in the installer. Crawling without JavaScript rendering needs no additional browser. The current fallback uses installed Chrome/Chromium or an explicit rendering.chromium_path or OPENSPIDER_CHROMIUM path.

For 1.0, an on-demand Chrome for Testing download into the app data folder is planned, with a fixed version and SHA-256 verification. This is not yet approved. The existing CLI already offers openspider --install-browser as a separate browser download; it does not yet provide the planned 1.0 delivery. Lighthouse uses separately installed Node/Lighthouse.

Updates and privacy

Help → “Check for updates” checks manually. “Automatically check for updates” in Settings → Updates is enabled by default and checks at startup at most once every 24 hours. The check sends only version, operating system and architecture, without a user identifier or crawl data. It is not telemetry. GitHub Releases hosts the manifest; GitHub technically sees your IP address. Optional integrations and crawled websites make their own network connections.

Disable the setting or set the following in settings.toml:

[updates]
check = false

Alternatively launch OpenSpider with OPENSPIDER_DISABLE_UPDATE_CHECK=1 in its process environment. Disabling checks prevents access to the update server. This is an app setting, not part of a crawl profile. Offline errors or a five-second timeout only produce a log entry at startup.

Updates can be downloaded in the background after your confirmation; release notes are shown. Choose “Install now and restart”, “Install on exit”, or “Install after crawl” while crawling. A running crawl is never forcibly restarted. HTTPS and valid update signatures are required; downgrades are rejected. The bundled CLI and registered tasks are updated too. Replace a separately installed CLI archive manually.

Until 1.0, betas are normal GitHub releases with latest.json and latest-beta.json. There is no channel selector in the UI. See the beta page for participation.

CLI and Linux

Linux x86_64 with glibc supports the core and CLI, including MCP over STDIO. Linux desktop, .deb/.rpm and Linux arm64 releases are unsupported. Extract the Linux archive and run its openspider executable. glibc compatibility depends on the release build; this is not a musl build. Keep the included license notices.

./openspider --version
./openspider --crawl https://example.com --headless --output-folder ./out --export-tabs "Internal:All" --save-crawl
./openspider --help
./openspider --check-update

On macOS use the full CLI path above or create your own PATH link. On Windows use openspider.exe in a new terminal. The CLI never checks automatically; --check-update returns exit code 0 when current and 10 when an update is available.

Scheduling

Create and enable a task in the app with a source, schedule and export destination. macOS uses LaunchAgents; Windows uses Task Scheduler. The computer must be available when the task runs. The scheduler invokes the bundled CLI. Run an existing task ID with openspider --run-task <ID>. Scheduled runs never check for updates. On Linux use your own cron/systemd scheduler with absolute CLI paths; no Linux desktop scheduler is promised.

Set up MCP

In the app’s MCP dialog choose a client and transport. STDIO starts a CLI process per connection; local HTTP requires the running app and authentication. You can also generate client configuration with:

openspider mcp --print-config claude-code
openspider mcp --print-config codex
openspider mcp --print-config cursor
openspider mcp --print-config claude-desktop

Copy the generated configuration into the client, set an absolute CLI installation path if needed and reconnect. Only read tools are enabled by default. Enable additional tool classes deliberately. Never share tokens or diagnostic packages publicly.

Uninstalling and user data

Back up important crawl files and close the app first. On macOS run "/Applications/OpenSpider.app/Contents/MacOS/openspider" --unregister-tasks before deleting OpenSpider from Applications. Deleting the app alone does not remove LaunchAgents. User files remain.

On Windows use Installed apps or uninstall silently:

C:\Tools\OpenSpider\uninstall.exe /S
msiexec /x OpenSpider.msi /qn /norestart

User data is retained by default. To explicitly delete it, add /REMOVEUSERDATA=1 for NSIS or REMOVEUSERDATA=1 for MSI. Installers remove program files, Start menu entries, their own PATH entry and tasks; check the log for task cleanup failures. The data option only removes the executing user’s standard %APPDATA%\OpenSpider and %LOCALAPPDATA%\OpenSpider folders, not other profiles, external crawls or OPENSPIDER_HOME folders.

On macOS data is in ~/Library/Application Support/OpenSpider/, logs in ~/Library/Logs/OpenSpider/ and cache in ~/Library/Caches/OpenSpider/. Remove these yourself after backup if desired. On Linux settings use $XDG_CONFIG_HOME/OpenSpider (default ~/.config), data $XDG_DATA_HOME/OpenSpider (default ~/.local/share), cache $XDG_CACHE_HOME/OpenSpider (default ~/.cache). Remove your cron/systemd entries and the CLI yourself. If OPENSPIDER_HOME is set, it holds settings, crawls, logs and cache. Remove external crawl files and client configurations separately.