Get the app from the project
Download from the project's own release channel and match the platform package. The app bundles a core, so the app version and the core version move together — a detail worth writing down, because field-level errors are often version questions.
What counts as input
| Input | Accepted as | Common mistake |
|---|---|---|
https://… subscription URL | A remote subscription | Pasting a login or product page |
A single vless://, trojan://, vmess:// link | A single proxy | Expecting it to behave like a subscription with many nodes |
| A Clash or sing-box configuration file | A configuration | Assuming any file with the right extension parses |
| A QR code | Whatever it encodes | Treating the whole message as a URL |
The five events behind “no nodes”
- Fetch. Did the request complete, and with what status?
- Content. Was the body a configuration, a login page, an empty body, or an error page?
- Parse. Did the content load, or did the parser reject a field?
- Selection. Is the newly added profile the active one?
- Start. Did the core start and open its listeners?
The first error in the log identifies the event. Reading only the last lines usually shows a symptom downstream of the cause.
Modes
| Mode | Coverage | Cost |
|---|---|---|
| System proxy | Applications that read proxy settings | Games, CLI tools and some store apps bypass it |
| VPN / TUN | Broader, subject to routes and exclusions | Needs a tunnel interface and permissions; interacts with other VPNs |
Start with the simpler mode. Move to VPN mode when a specific application needs it, and record the pre-change DNS and routing state so you can restore it.
Platform notes
- Windows: VPN mode needs a helper process. An elevation error at connect time is a local permission question, not a node question.
- macOS: first launch requires approving a system extension or VPN configuration. A database migration error at startup is a local data question.
- Linux: TUN needs the relevant capability or a privileged helper. A bare exit code usually means a prerequisite process never started.
- Android and iOS: the VPN indicator reflects an active configuration; it does not prove traffic passed.
Reading the first error
| Message | Layer |
|---|---|
| HTTP 401/403/404/429 | Fetch and authorisation |
unmarshal error with a field name | Parse: a field this build does not accept |
| Profile exists, list empty | Selection, filtering or core start |
| Exit status with a number | A helper process failed to start |
duplicate column name | Local database migration on macOS |
Verify
- One real HTTPS request with the intended mode active.
- Observed exit, if region matters.
- Whether the same request works in the other mode — that separates capture from forwarding.
- App version, core version, platform and the time.
Scope
This page describes import and mode selection. Interface wording differs by platform and release, and the project's own documentation is the authority for each. Nothing here evaluates a provider.