Guide

Quick start: install → import → pick a node → take over → verify

First time? Follow these five steps. Advanced topics (dual cores, JS overrides) come later in the guide and can wait.

Two cores: mihomo ↔ sing-box

Crossbow supports mihomo and sing-box. Before switching, check that the target core supports your subscription’s protocols and rules. Configuration formats are converted automatically, followed by a core restart.

JS overrides: make the configuration yours

Configuration → Overrides → New override → JS script. Write function main(config) and return the transformed configuration. Scripts run in a sandbox without network or file access and are tested on save.

• Prerequisite: your subscription contains nodes whose names include 香港 (HK) or JP — otherwise the filtered list is empty.
• The sample rules reference an AUTO group that must exist in your subscription; if the name differs, adjust the rules or remove the reference — the dry run on save exposes dangling references.

function main(config) {
  // Keep nodes whose names include 香港 (Hong Kong) or JP.
  config.proxies = config.proxies.filter(p =>
    /香港|JP/.test(p.name)
  );

  // Route streaming through 自动选择 (Auto select), then use MATCH.
  config.rules = [
    "DOMAIN-SUFFIX,netflix.com,自动选择",
    "GEOIP,CN,DIRECT",
    "MATCH,自动选择",
  ];
  return config;
}

Deep-link import from any page

Put a link like this on a web page. Users with Crossbow installed can open it to confirm an import:

crossbow://import?url=https%3A%2F%2Fexample.com%2Fsub

URL-encode the url parameter. For users without Crossbow, provide a fallback to the download page. This works well in provider or self-hosted service documentation.

Live menu bar traffic

When the core is running, the macOS menu bar shows upload and download rates, refreshed every second in a compact, fixed-width layout. It also works in lightweight mode and disappears when the core stops. This feature is currently macOS-only.

Mixed port & bypass rules

The shared HTTP and SOCKS5 port defaults to 7897. In Settings → Network & core, choose Edit beside the port, then Apply or press Enter. Escape cancels; moving focus does not save. A running core may briefly restart. The system proxy bypasses local and private network addresses.

If another proxy app holds port 7897, startup reports the conflict. Choose an unused port in Settings.

To share the proxy with devices on the same network, enable Allow LAN and use this computer’s LAN IP and mixed port. This listens on 0.0.0.0; enable it only on trusted networks and review the system firewall rules.

Linux preview: check the support scope first

The community x86_64 archive is mainly tested on CachyOS + niri / Wayland. Thanks to YangYuS8 for the adaptation and field feedback. Other distros and desktop environments are not fully verified yet.

Release and development status differ. Linux background work after closing the window, cold-start deep links, and native notification improvements are on main. Check whether your downloaded version includes them in the release notes. Detailed validation records are in the Linux testing document.

Choosing between the system proxy and TUN

On macOS / Windows, start with the system proxy in Overview for everyday browsing. Enable TUN in Settings for apps that ignore system proxy settings. Both can run together with independent controls. After disabling TUN, check the system proxy state and connectivity.

Lightweight mode & tray

Enable Lightweight mode in Settings. Closing the window keeps the proxy and tray running while releasing interface memory. Click the tray icon to reopen. Use Quit in the tray menu to exit completely. A running core is handed off and adopted again on the next launch.

Track actionable problems in the notification center

Click the bell to see recent notifications. Unread and unresolved are different states: marking everything as read does not fix a failure. Once it is fixed through Diagnostics or Settings, the original record shows recovery.

Theme, language, and routine setting changes do not repeat success messages. Tasks continue after you dismiss progress notifications; failures offer redacted details. Records last only for the current session. Use logs for longer-term investigation.

Subscription updates: see what changed

Select a subscription in Configuration → Sources. Review its update status before requesting a manual update.

Restore a configuration snapshot

The five most recent snapshots are kept before saving. Choose Configuration recovery on the Configuration page and select a restore point by time and contents.

Troubleshoot using connection evidence

Core operation, traffic takeover settings, and network connectivity are different states. A running core does not prove that a browser can reach a website.

In-app updates: check, download, install

On macOS and Windows, check the version in Settings → App & updates. The Linux preview requires a new archive downloaded manually.

Windows installation and the TUN service

The Windows x64 installer includes CrossbowService, which is required for TUN. If installation or an update reports locked files, close other Crossbow instances and retry as instructed. Use the full installer to repair a missing service. Check the release notes for signing and support details.

Windows installation, service, and upgrade guide ↗

Where configuration & data live

On macOS, data is stored in ~/Library/Application Support/com.richard.crossbow/: store.json (subscriptions, settings, and overrides, with five snapshots kept before saving), runtime/ (runtime state and logs), and binaries/ (core binaries). Data from com.crossbow.app data migrates automatically; backing up the new directory before an upgrade is a good idea.