Skip to content

SpellVPN User Guide

Jump to bottom
cnc980 edited this page Jul 8, 2026 · 1 revision

Last updated: 2026-07-08

What This App Runs

SpellVPN runs user-imported sing-box configurations through an iOS Packet Tunnel extension. It does not include bundled VPN server accounts, sell proxy nodes or host user traffic. You need a valid sing-box config or a supported proxy subscription from a server you are authorized to use.

SpellVPN is designed as a paid-download app with no in-app purchases, no advertising SDK and no analytics SDK in the current build.

Devices

This build supports iPhone and iPad. The iPad version uses the same VPN runtime and import flow. Real VPN traffic still requires a signed physical device with the Packet Tunnel entitlement; the simulator can only show the UI and run non-VPN tests.

Language

The app follows the iOS system language automatically. This build includes localized app strings for English, Simplified Chinese, Traditional Chinese, Japanese, Korean, Spanish, French, German, Brazilian Portuguese, Russian and Arabic. If the device language is not included, iOS falls back to English.

Import Methods

On the Dashboard, tap the + button in the top-right corner:

  • Scan QR Code: opens the camera and imports the first QR code it reads.
  • Import QR from Photos: picks an image from the photo library and scans the first QR code found in it.
  • Import Subscription URL: downloads and parses an http:// or https:// subscription URL.
  • Import Proxy Link: imports one proxy URI such as ss://, vmess://, vless://, trojan://, hysteria2://, hy2:// or tuic://.
  • Import File: imports a local .json or text file from Files/iCloud.
  • Paste Config or URL: reads the clipboard.
  • Health Check: checks the imported node.

The Config tab also includes import and editing tools for advanced use:

  • Paste Config, URL or Link: reads the clipboard.
  • Import JSON File: imports a local .json or text file from Files/iCloud.
  • Import QR from Photos: picks an image from the photo library and scans the first QR code found in it.
  • Subscription URL: downloads an http:// or https:// subscription URL.
  • Manual text editor: paste content into the editor and tap Use Draft.
  • URL Scheme: open a supported app URL from another app or web page.

Supported import content:

  • complete sing-box JSON with a tun inbound and a real proxy outbound
  • plain text containing one or more supported proxy links
  • Base64 subscription text containing proxy links
  • ss://
  • vmess://
  • vless://
  • trojan://
  • hysteria2:// and hy2://
  • tuic://

URL Scheme Examples

Recommended schemes:

  • spellvpn://
  • spellvpn-import://

Compatibility schemes:

  • magicvpn://
  • magicvpn-import://
  • supervpn://
  • supervpn-import://

Import a remote subscription:

spellvpn://subscribe?url=https%3A%2F%2Fexample.com%2Fsub.txt

Import a proxy link:

spellvpn://import?link=ss%3A%2F%2F...

Import encoded config text:

spellvpn://import?data=BASE64_OR_PERCENT_ENCODED_CONFIG

Connect

  1. Import a config.
  2. Confirm the Active section says Ready.
  3. Return to Dashboard.
  4. Tap Connect.
  5. Approve the iOS VPN permission prompt.

Real VPN traffic only works on a signed physical iPhone or iPad. The simulator can show the UI and run tests, but it cannot carry real Packet Tunnel traffic.

Virtual Adapter Mode

The Config tab includes a Virtual Adapter section. These settings are stored in the VPN profile, applied to the Network Extension route settings, and also written into the active sing-box tun inbound before the Packet Tunnel starts.

  • Full Tunnel: installs the system default route when a signed Packet Tunnel is running, default traffic routing is enabled and Auto Route is on.
  • Enhanced Fake-IP: routes the 198.18.0.0/15 fake-IP range through the tunnel.
  • Split Tunnel: routes the CIDR ranges listed in Include Routes. If no include route is set, the tunnel falls back to the fake-IP route.

Available adapter fields:

  • Stack: system, gvisor or mixed.
  • MTU.
  • Auto Route.
  • Strict Route.
  • IPv6.
  • Include Routes.
  • Exclude Routes.

Privacy Policy Link

The Settings tab shows a Privacy Policy link only after SpellVPNPrivacyPolicyURL is set in SuperVPNApp/Info.plist. This must be a public https:// URL. Local Markdown files, private network addresses and placeholder domains are ignored.

The old SuperVPNPrivacyPolicyURL key is still accepted for backward compatibility, but new builds should use SpellVPNPrivacyPolicyURL.

Export

After a config is active, the Config tab shows Export actions:

  • Copy Active Config
  • Export JSON File
  • Share via System Sheet
  • Show Config QR

Large configs may be too big for a single QR code. Use JSON file export or the system share sheet in that case.

Troubleshooting

  • "Config must include a sing-box tun inbound": import a complete sing-box JSON file, or use a supported proxy link/subscription so the app can generate the tun config.
  • "Proxy outbound must include server and server_port": the imported link is missing server information or uses an unsupported format.
  • Simulator warning on Connect: install the signed build on a real device.
  • VPN starts but IP does not change: check the imported sing-box route and proxy server; the app only routes according to that config.

Clone this wiki locally