Documentation

Last updated: February 2026

Getting started

Prismway runs on iPhone, iPad and Apple TV. This section takes you from installation to your first connection in a few minutes.

System requirements

iPhone and iPad: iOS 16.0 or later.
Apple TV: tvOS 17 or later.
Control Center toggle: requires iOS 18 or later.
A subscription link or server configuration from your provider.

Your first connection in 3 steps

Import your subscription. Paste the link from your provider, or scan the QR code on their website.
Tap the big button. One tap on the home screen connects you — smart routing picks the best line.
Allow the VPN permission. iOS asks once; this is required for the app to route traffic.

The VPN prompt is shown by iOS, not by Prismway. All routing happens entirely on your device — traffic contents are never uploaded anywhere.

Subscription management

Subscriptions are the starting point of every config. Prismway keeps them fresh, visible and safe to share.

Three ways to import

Paste a link: copy the subscription URL from your provider and add it on the subscription screen.
Scan a QR code: point the camera at the code on your provider's website or dashboard.
Clipboard sniffing: when a subscription link is on your clipboard, the add screen detects it and offers a one-tap import. The clipboard is read only when you open this screen, and its content never leaves your device.

Automatic updates

Subscriptions refresh automatically in the background on a schedule you choose. Every update produces a diff preview so you can see exactly what changed before it takes effect — and your overrides are never touched (see Overrides & the four layers).

Traffic and expiry at a glance

For providers that expose usage information, the subscription card shows used and total traffic plus the expiry date, with a gentle reminder before the plan runs out.

Multiple configs, one-tap switching

Keep as many configs as you need — multiple providers, self-hosted servers or imported files. Switch the active config from the home screen; each config keeps its own overrides, rules and plugin state.

Sharing configs safely

Share a config as a link or QR code. Sensitive fields — server passwords, UUIDs, private keys — are redacted by default, and you review exactly what will be sent before sharing.

Only include credentials when you fully trust the recipient: anyone holding an unredacted link can use your subscription and see its servers.

The three modes

One engine, three interfaces. Modes change information density — never the capability ceiling. Everything you configure in a simpler mode keeps working in a deeper one.

Mode	Who it's for	What you see
Simple	Everyday users	One screen, one button. Green means good.
Advanced	Power users	Subscriptions, policy groups, rules, overrides and plugins.
Expert	Developers	Everything in Advanced, plus request inspector, MitM, rewrite engine and scripts.

Switching modes

Switch any time in Settings → Mode. The interface updates instantly — no restart, no reconfiguration, nothing to migrate.

Progressive disclosure by design: Expert tools stay hidden until you ask for them, and switching back to a simpler mode never discards anything you configured — it simply stays out of your way.

Policy groups & rules

Rules match traffic and hand it to a policy group; the group decides which node carries it. Prismway supports seven group types:

Type	Behavior	Best for
`select`	You pick the node manually.	Hands-on control as the default exit.
`url-test`	Tests all nodes periodically and uses the fastest.	Everyday browsing on stable lines.
`fallback`	Uses the first healthy node in your order.	Reliability-first setups with a clear priority.
`load-balance`	Spreads connections across healthy nodes.	Many parallel connections, such as downloads.
`ssid`	Switches node or strategy by Wi-Fi network.	Different behavior at home, at the office and on cellular.
`smart`	Self-learning group that picks by latency and availability history, with switch hysteresis to avoid flapping.	Set-and-forget routing that improves over time.
`relay`	Chains nodes: traffic enters through one node and exits through another.	Fixed entry/exit combinations, such as a stable relay in front of a fast exit.

Rule sets

Write rules one by one, or load entire rule sets: GEOSITE for domain categories, GEOIP for country IP ranges, and MRS binary rule sets for fast matching of very large lists. Remote rule sets update automatically alongside your subscription.

Per-app routing

Where iOS allows it, Prismway makes routing decisions per app, and ships with reviewed direct-connection presets for banking and payment apps — so your bank never sees an unexpected IP address. Presets are suggestions; you always keep the final say.

Rule order matters: the first matching rule wins. Put exceptions above broad matches, and keep the final catch-all rule at the bottom.

Overrides & the four-layer model

Every effective config is built from four layers that merge like CSS cascades: higher layers win, lower layers stay untouched.

Layer	What it holds	Can you edit it?
L1 · Subscription	Your provider's config	No — always read-only
L2 · Overrides	Your declarative tweaks: rename groups, pin nodes, add rules	Yes
L3 · Plugins	Patches contributed by installed plugins	Indirectly — by enabling or disabling plugins
L4 · Preferences	App-level settings such as DNS and per-app routing	Yes

Zero loss on subscription updates

When a subscription updates, only L1 changes. Your overrides re-apply on top — guaranteed. Every update offers a diff preview of the effective config before it goes live.

Visible conflict reports

If an override no longer matches the updated subscription — a renamed group, a removed node — Prismway shows a visual conflict report: what applied, what was skipped, and a guided fix for each item.

Nothing fails silently. A conflict never blocks an update — it is reported, and the effective config always stays valid.

Plugin center

Plugins add capabilities without touching your base config: ad-blocking rule sets, streaming availability checks, dashboard enhancements and more.

Reviewed official source

Every plugin in the official source is human-reviewed. Each listing shows the permissions the plugin requests — network access, rewrite, script runtime — before you install.

Bring what you already have

Prismway imports the plugin formats you already use. Every import produces a conversion report: what worked, what was skipped and why.

Surge Modules (.sgmodule)
Loon plugins (.plugin)
Quantumult X remote resources (rewrite and filter lists)

Traffic impact view

Each plugin's impact view shows how many requests it rewrites, intercepts or blocks — so a slow network is never a mystery.

Third-party plugins run with the permissions you grant them. Prefer the reviewed official source, and check permission requests before installing from anywhere else.

Expert mode tools

Expert mode turns your phone into a complete debugging toolchain. Everything runs on-device.

Request inspector

Record and inspect HTTP(S) requests with headers, bodies and timing. When a rewrite applies, compare before and after side by side, and export a standard HAR file to share or analyze on your computer.

MitM console

The MitM console decrypts HTTPS traffic for hosts you explicitly list. It is off by default; enabling it requires installing a local CA certificate in iOS Settings, and a visible indicator stays on screen while it is active.

Only enable MitM for hosts you own or are authorized to debug. The CA certificate never leaves your device and can be removed at any time from iOS Settings.

Rewrite engine

Rewrite requests and responses declaratively — redirects, header edits, body transforms with jq-style expressions — or serve full Mock responses from local files during development.

Script engine

The JavaScript engine runs scripts inside a permission sandbox: network, storage and notifications are granted per script, per capability. Scripts run on events, on a cron schedule, or on demand from a widget.

HTTP API, URL Scheme & Shortcuts

A local HTTP API exposes status, switching and trigger endpoints for automation — bound to your LAN by default, never to the public internet. Together with the prismway:// URL Scheme and a built-in Shortcuts library, anything the app can do, you can automate.

Sync & widgets

iCloud sync

Configs, subscriptions, overrides and plugin state sync across iPhone, iPad and Apple TV through your own iCloud account. Data passes only through Apple's iCloud infrastructure under your Apple ID — Prismway runs no servers and can never see it.

Home Screen widgets

Widgets show connection status, the current node and traffic at a glance — and connect or disconnect with a tap, without opening the app.

Control Center toggle

On iOS 18 and later, add the Prismway toggle to Control Center for one-swipe control from anywhere in the system.

Remote controller

The remote controller lets you manage a family member's device from your own — with their explicit, revocable approval. Set up the subscription once, keep it running for them, and read their network checkup report when they ask for help.

Remote control requires approval on the managed device and can be revoked there at any time. It works over your own iCloud — no Prismway servers involved.

Troubleshooting

Network checkup

Network checkup runs a structured diagnosis — DNS, connectivity, node latency, rule matching — and answers in traffic lights, not jargon. One tap copies a plain-text report you can send to a friend, your provider, or us.

Common errors and what they mean

Error	What it means
Auth failed / unauthorized	The server rejected your credentials — check that the subscription is up to date and has not expired.
Handshake timeout	The node is unreachable from your network — try another node or run a network checkup.
DNS resolution failed	Domain resolution is broken — switch the encrypted DNS preset or check your local network.
MitM certificate not trusted	The target app rejects the local CA — make sure the certificate is installed and fully trusted in iOS Settings.
No healthy nodes in group	Every node in the group failed its last test — update the subscription or widen the group's node list.

Sending feedback

Settings → Send feedback builds a diagnostic report with sensitive data redacted — server addresses, keys and browsing history are stripped before anything leaves your device, and you review the exact report before sending.

Still stuck? Email [email protected] — attaching a checkup report or feedback bundle gets you a faster, more precise answer.

Frequently asked questions

What is the difference between Free and Pro?

Feature	Free	Pro
Full Simple mode	✓	✓
Subscriptions, policy groups, rules and overrides	✓	✓
Official plugin source, iCloud sync, widgets, checkup	✓	✓
Expert mode: request inspector, MitM, rewrite, scripts	—	✓
HTTP API and remote controller	—	✓

Pro is a one-time purchase — no subscription, and the future Mac version license is included.

How do I restore my purchase?

Pro is tied to your Apple ID, not to a device. On a new device, sign in with the same Apple ID and open Settings → Upgrade → Restore purchase.

Does Pro support Family Sharing?

Yes. Pro supports Apple Family Sharing — up to six family members use Pro at no extra cost, each with their own iCloud-synced configs.

How do refunds work?

Purchases are handled entirely by the App Store: request a refund at reportaproblem.apple.com. In the European Union you additionally have a statutory 14-day right of withdrawal for digital purchases, exercised through Apple.

What does Prismway do with my data?

Nothing. Zero telemetry by architecture: no accounts, no analytics SDKs, no servers holding your data — every App Store privacy label reads “Data Not Collected”. Read the full Privacy Policy.

Where are the Terms of Service?

Using Prismway is subject to the Terms of Service.