Health Checks
Diagnose engine, network, BitTorrent, disk, and configuration health from a single panel.
The desktop app ships a Health panel that aggregates cheap probes across the engine, the host system, and the saved configuration into a single colour-coded report. It is the first place to look when a download is misbehaving and you want to find out whether the problem is the network, the disk, the proxy, BitTorrent connectivity, or a stale config value.
Categories
The report is grouped into the following categories. You can request a subset (or run the slow probes) by passing options to the underlying Tauri command — see Programmatic Access below.
| Category | What it checks |
|---|---|
general | Engine running state, uptime, app version, RPC endpoint, empty-secret warning when the RPC host is not loopback |
network | BT and DHT listen-port configuration, IPv6 listener flag, proxy URL validity and reachability (slow probe) |
bittorrent | Encryption policy, UPnP mappings, LSD listener, BT session port and torrent count, DHT routing-table size, peer tuning limits, tracker reachability (slow probe) |
disk | Download directory writability, free space, file allocation strategy, recent save paths (failures demoted to warnings) |
system | Auto-launch state, "prevent sleep while downloading" toggle, OS-level sleep inhibitor activity |
config | Startup-only keys that changed since the engine started and need a restart to apply |
logs | Log directory location, error/warning counts in the latest log file's tail (last 1 MiB) |
tools | External helper presence in PATH: yt-dlp (fail if missing), ffmpeg (warn if missing — video+audio merge fallback). Skipped entirely on Android |
Each individual check returns one of:
ok— Healthywarn— Working but suboptimal (e.g. UPnP enabled but no router responded)fail— Broken (e.g. download dir not writable)skipped— Not run (slow probe disabled, or feature inactive). The DHT check also reportsskippedduring the first 60 s after engine start while the routing table bootstraps
The category status is the worst of its checks; the overall status is the
worst across categories. Severity order is fail > warn > skipped >
ok, so a category of only skipped checks rolls up as skipped.
Suggested Fixes
Each check can carry a structured fix hint that the panel turns into a
button:
| Fix kind | Action |
|---|---|
open-preference | Jumps to a specific Preferences pane (target field) |
restart-engine | Quits and relaunches the embedded engine |
open-log-dir | Reveals the log directory in the OS file manager |
Programmatic Access
The panel calls one Tauri command:
import { invoke } from "@tauri-apps/api/core";
const report = await invoke("run_health_checks", {
// Optional: limit to a subset of categories
categories: ["network", "bittorrent"],
// Optional: enable slow probes (proxy reachability, etc.)
slowProbes: true,
});The response shape is:
type HealthStatus = "ok" | "warn" | "fail" | "skipped";
interface HealthReport {
generatedAtMs: number;
engineRunning: boolean;
overallStatus: HealthStatus;
categories: Array<{
id: string;
status: HealthStatus;
checks: Array<{
id: string;
status: HealthStatus;
message: string;
fix: { kind: string; target: string | null } | null;
details: unknown | null;
}>;
}>;
logPath: string;
}[!INFO] Health checks are not exposed over JSON-RPC. They depend on Tauri-side state (autostart manager, sleep inhibitor) that the standalone CLI engine does not own.
When to Run Slow Probes
Slow probes are skipped by default so the panel stays snappy. There are currently two:
- Proxy reachability: a
HEADrequest through the configured proxy tohttps://www.cloudflare.com/cdn-cgi/trace, capped at 4 s. - Tracker reachability: a
HEADrequest per unique HTTP(S) tracker URL across active torrents, 3 s timeout each, 8 in flight at a time. UDP and WebSocket trackers are skipped; an HTTP 400 response counts as reachable (announce endpoints rejectHEADwithout a query).
Re-run with slowProbes: true when you actually suspect outbound
connectivity is the issue.