Supported Headers

When Prizrak-Box fetches a remote subscription, it reads specific HTTP response headers from the server. These headers let subscription providers control profile metadata, traffic display, automatic updates, logo, announcements, and more.

Headers are case-insensitive. Unknown headers are silently ignored.

Inline headers

If your server cannot set HTTP response headers (e.g. a static file host), you can embed headers as comments at the top of your subscription content:

#profile-title: My VPN
#subscription-userinfo: upload=1073741824; download=5368709120; total=107374182400; expire=1893456000

Inline comment headers use the same names as HTTP headers, prefixed with #. They act as fallback values — HTTP response headers always take priority over inline headers.

Note

Headers marked with are managed automatically by the Remnawave panel. You do not need to add them manually via Response Rules or the subscription header settings — Remnawave sends them on its own.

---

Profile Metadata

Profile-Title

The display name for the subscription in Prizrak-Box.

Property	Value
Type	string
Encoding	Plain UTF-8 or Base64 (base64: prefix)

Example:

Profile-Title: My VPN Subscription
Profile-Title: base64:TXkgVlBOIFN1YnNjcmlwdGlvbg==

If Profile-Title is absent, the app falls back to the filename from the Content-Disposition header, then to a generated name like Sub-2024-01-01.

Profile-Logo

URL of an image to use as the subscription logo in the app.

Property	Value
Type	string (URL)
Supported formats	PNG, SVG
Max file size	2 MB
Allowed schemes	http, https

Example:

Profile-Logo: https://example.com/logo.png

The logo is downloaded at fetch time and cached locally. An empty or invalid URL clears the cached logo.

Content-Disposition

Used as a fallback source for the profile title when Profile-Title is absent.

Property	Value
Type	string
Parsed field	filename parameter

Example:

Content-Disposition: attachment; filename="my-vpn.yaml"

The filename value (without extension) becomes the profile title if Profile-Title is not set.

---

Traffic Information

Subscription-Userinfo

Reports traffic usage statistics displayed in the profile card.

Property	Value
Type	string (semicolon-separated key=value pairs)
Fields	upload, download, total, expire
Units	Bytes (for traffic fields), Unix timestamp (for expire)

Example:

Subscription-Userinfo: upload=1073741824; download=5368709120; total=107374182400; expire=1893456000

Field	Description
upload	Bytes uploaded
download	Bytes downloaded
total	Total traffic quota in bytes
expire	Expiry time as Unix timestamp

---

Update Settings

Profile-Update-Interval

Sets the automatic refresh interval for this subscription.

Property	Value
Type	integer
Unit	Hours

Example:

Profile-Update-Interval: 24

When this header is present, Prizrak-Box automatically re-fetches the subscription at the specified interval in hours.

---

Links

Profile-Web-Page-Url

A URL for the subscription provider’s home page or portal.

Property	Value
Type	string (URL)

Example:

Profile-Web-Page-Url: https://myvpn.example.com

Displayed in the profile detail view as a tappable link.

Support-Url

A support or contact URL (e.g. Telegram channel, help desk).

Property	Value
Type	string (URL)

Example:

Support-Url: https://t.me/myvpn_support

Displayed alongside the profile for users to reach support.

Subscription-Renew-Url

A direct link to the subscription’s renewal/payment page.

Property	Value
Type	string (URL)

Example:

Subscription-Renew-Url: https://myvpn.example.com/renew?id=abc123

When present, the app shows a “Renew subscription” entry point in several places: the profile editor, an icon next to the profile in the main window and in the profile list, and — when a reminder threshold from Notify-Expire-Days/Notify-Traffic-Percent below is currently crossed — a full-width button under the profile card. Absent header means none of these appear; the profile otherwise works as normal.

---

Subscription Reminders

These headers configure client-side reminders about an approaching or reached subscription expiry, and about traffic usage — shown as native OS notifications and, while a threshold is crossed, as a “Renew subscription” button in the app (see Subscription-Renew-Url above).

Notify-Expire-Days

Days-before-expiry thresholds at which to remind the user.

Property	Value
Type	string (comma-separated integers)
Range	1–365 (out-of-range values are dropped)

Example:

Notify-Expire-Days: 1,3,7

Notify-Traffic-Percent

Traffic-usage-percentage thresholds at which to remind the user.

Property	Value
Type	string (comma-separated integers)
Range	1–100

Example:

Notify-Traffic-Percent: 80,90,100

Notification-Subs-Expire

A simplified opt-in for panels that don’t want to specify exact days (some Happ-style panels only send this).

Property	Value
Type	string (boolean)
Values	true

Example:

Notification-Subs-Expire: true

If true and Notify-Expire-Days is absent, the app enables expiry reminders using built-in default thresholds of 1, 3, and 7 days.

These headers require an explicit opt-in

Expiry and traffic notifications only fire when the panel sends at least one of Notify-Expire-Days, Notify-Traffic-Percent, or Notification-Subs-Expire. This is true even if Subscription-Userinfo already carries expire/total — the app does not invent reminder thresholds on its own. If none of the three headers are sent, no reminder notifications are shown, regardless of the user’s local “Subscription reminders” setting (that setting is a permission to show them, not a source of thresholds).

Notifications show the actual time left

The thresholds only decide when a reminder is raised. The text is not the threshold: the notification carries the exact expiry date and time (for example, “Subscription expires 05.10.2026, 14:30”), and the window that opens when you click it is recalculated from the profile at that moment (“expires in 1 d 2 h”, “expired”, the current percent of traffic used). A reminder that has been waiting for a day therefore never says “4 days” when a day is left.

The renew button uses the furthest threshold

The “Renew subscription” button (see Subscription-Renew-Url) reacts to the largest value in Notify-Expire-Days. For example, with Notify-Expire-Days: 1,5,10 the button appears 10 days before expiry and stays visible through the 10 → 5 → 1 → expired countdown, not only at the exact 1/5/10-day marks. Unlike push notifications, the button also works with no Notify-Expire-Days header at all — it falls back to the built-in 1/3/7-day defaults as a courtesy — but for traffic it never invents a percentage: without an explicit Notify-Traffic-Percent, the button ignores traffic usage entirely.

---

Announcements

Announce

A text announcement displayed in the app as a banner on the profile card.

Property	Value
Type	string
Max length	200 characters
Encoding	Plain UTF-8 or Base64 (base64: prefix)

Examples:

Announce: Maintenance scheduled for Saturday 02:00–04:00 UTC
Announce: base64:TWFpbnRlbmFuY2Ugc2NoZWR1bGVk

Announce-Url

A URL linked from the announcement banner.

Property	Value
Type	string (URL)

Example:

Announce-Url: https://status.myvpn.example.com

Tapping the announcement banner in the app opens this URL.

---

URL Migration & Fallback

These headers implement subscription URL migration — allowing providers to move subscriptions to a new address without users manually updating their URL.

new-url

Instructs the client to replace the entire subscription URL with a new one.

Property	Value
Type	string (full URL)
Priority	Highest — takes precedence over new-domain
Hops	Max 3 consecutive migrations

Example:

new-url: https://new.example.com/subscription/abc123

After receiving this header, Prizrak-Box immediately saves the new URL and re-fetches from it. The original URL is replaced permanently in the profile.

new-domain

Instructs the client to replace only the hostname of the subscription URL, preserving the path and query string.

Property	Value
Type	string (bare host, no scheme, no path)
Example value	new.example.com or new.example.com:8443

Example:

new-domain: cdn.example.com

If the current subscription URL is https://old.example.com/sub/abc, this produces https://cdn.example.com/sub/abc.

fallback-url

An alternative full URL to try if the primary subscription URL fails (non-2xx or connection error).

Property	Value
Type	string (full URL)
Persisted	Yes — saved to the profile for future fetches

Example:

fallback-url: https://backup.example.com/subscription/abc123

Prizrak-Box tries the primary URL first. If it fails, it falls back to fallback-url. The fallback value is updated (or cleared) on every successful fetch.

fallback-domain

An alternative domain to substitute into the primary URL if it fails.

Property	Value
Type	string (bare host)
Persisted	Yes — saved to the profile

Example:

fallback-domain: backup.example.com

If the primary URL is https://main.example.com/sub, this fallback tries https://backup.example.com/sub.

Fallback priority

The fetch order is: primary URL → fallback-url → primary URL with fallback-domain. The first response with a 2xx status code is used.

---

Mobile UI Controls Android & iOS

The following headers are supported by the mobile versions of Prizrak-Box (Android and iOS). They allow subscription providers to control certain UI elements and behaviour of the mobile client.

All values are applied once on subscription fetch and persist in the profile until the next update.

pxa-latency-dots

Controls how proxy latency is displayed in the proxy list.

Property	Value
Type	integer
Values	0 = latency numbers, 1 = latency dots

Example:

pxa-latency-dots: 1

Happ compatibility

For compatibility with providers that previously used the Happ app, the following aliases are also supported:

• ping-result: time → equivalent to pxa-latency-dots: 0
• ping-result: icon → equivalent to pxa-latency-dots: 1

If both pxa-latency-dots and ping-result are present, pxa-latency-dots takes priority.

pxa-simple-mode

Activates a simplified interface mode — shows only the first select proxy group of your Mihomo configuration on the app’s main screen.

Property	Value
Type	integer
Values	1 to enable

Example:

pxa-simple-mode: 1

pxa-global-mode-mp

Shows the Global Mode menu item in the bottom-left corner of the current profile card when a VPN connection is active. When not set (or 0), the item may be hidden.

Property	Value
Type	integer
Values	1 to show

Example:

pxa-global-mode-mp: 1

pxa-conns-view-mp

Shows the Connections view menu item in the bottom-left corner of the current profile card when a VPN connection is active.

Property	Value
Type	integer
Values	1 to show

Example:

pxa-conns-view-mp: 1

pxa-rp-mp

Shows the Rules Provider (RP) menu item in the bottom-left corner of the current profile card when a VPN connection is active.

Property	Value
Type	integer
Values	1 to show

Example:

pxa-rp-mp: 1

pxa-theme

Sets the look of the client on Android, iPhone, iPad and Apple TV for the profile: the profile card colour, the accent colour, the mode (light / dark) and the home screen background.

Property	Value
Type	string (key=value pairs separated by semicolons)
Encoding	UTF-8 or Base64 (base64: prefix)
Applies to	card: always, to the card of its own profile; accent, mode, background: while the profile is active

Parameter	Values	Description
card	#RRGGBB or auto	Profile card colour: in the deck on the home screen, on the collapsed card above the active one, in the opened profile, in the Profiles tab on iPad, on Apple TV. auto takes it from the profile logo
accent	#RRGGBB, auto or user	Accent colour: tabs, buttons, links, home screen backgrounds. auto uses the card colour. user keeps what the user chose in Accent Colour
mode	auto, light, dark or user	App appearance. auto follows the system, light is light, dark is dark. user keeps what the user chose in Visual
background	topography, clean, bigGhost, dotGrid, hem, signal, ghostPattern, cucumber, mushroomia or user	Home screen background. user keeps what the user chose

Every parameter is optional. A parameter missing from the header comes from the user’s own settings, which works the same as user. An explicit user says that the profile deliberately leaves this parameter to the user.

Keys and values are case-insensitive, and spaces around = and ; are ignored. Unknown parameters and invalid values are skipped, the rest is applied. A colour is written only as # followed by six hexadecimal digits.

card has no user value: the user has no own choice of card colour, it always comes from the logo, which is what auto does.

Colours:

• If card is so light that white text on it is hard to read, the card is darkened, as it already is with light logos.
• accent is applied as given, the same as a colour from Personalisation.

Full example:

pxa-theme: accent=#1fb5c9; card=#0f3d4a; mode=dark; background=mushroomia

The same header in Base64:

pxa-theme: base64:YWNjZW50PSMxZmI1Yzk7IGNhcmQ9IzBmM2Q0YTsgbW9kZT1kYXJrOyBiYWNrZ3JvdW5kPW11c2hyb29taWE=

Only the accent and card colours:

pxa-theme: accent=#8e5be8; card=#3b2a6b

The mode and the background stay as the user chose them.

A card colour, with the accent taken from the card:

pxa-theme: card=#c9484f; accent=auto

Only a card colour, everything else explicitly left to the user:

pxa-theme: card=#5a2d14; accent=user; mode=user; background=user

Appearance follows the system:

pxa-theme: accent=#8e5be8; mode=auto

The appearance follows Android or iOS, even if the user chose light or dark in the app.

Settings → Visual

• If the active profile has this header, a “Profile theme” switch appears at the top, with a caption saying what the profile sets, for example “Provider sets accent, card, mode, background”. Parameters set to user are not listed in the caption.
• Items set by the profile (Mode, Accent Colour, Home Background) are shown with a lock and cannot be changed.
• Accent Colour shows a banner at the top, “Colour set by profile “Provider"". The list and Personalisation are dimmed, and the choice in them is kept.

How the user’s settings come back

• There is one “Profile theme” switch for the whole app. Turning it off brings back the user’s own settings: accent, mode, background, and card colours come from the logos again.
• The user’s settings are never overwritten. They also apply when switching to a profile without this header (or the defaults, if the user never changed them).
• If the header disappears on the next subscription update, or no valid parameter is left in it, the profile theme is removed.

Differences from pxd-theme (desktop):

• No image, transparency, blur or dim: the mobile client has no background image or transparent panels. background with built-in backgrounds is used instead of image.
• card and the user value are added.
• accent=auto takes the card colour, not a colour from a background image.

---

Desktop UI Controls Desktop only

The following headers are supported only by the desktop versions of Prizrak-Box (Windows, macOS, Linux). They let subscription providers control certain UI elements of the desktop client.

The value is applied on subscription fetch and persists in the profile until the next update.

global-mode

Controls whether the mode switcher (Rule / Global / Direct) is shown in the left sidebar and in the system tray menu.

Property	Value
Type	string
Values	false or 0 to hide the switcher; any other value (or absent) shows it

Examples:

global-mode: false
global-mode: 0

If the value is false (case-insensitive) or 0, the whole mode switcher (Rule / Global / Direct) is hidden from the left sidebar and from the system tray menu for this profile, provided it is the active profile (primary, or otherwise selected). Any other value, or the absence of the header, keeps the switcher visible.

Note

If the profile is currently in Global mode when this header hides the switcher, the app automatically switches the active profile back to Rule mode.

pxd-theme

Sets the desktop client’s look for the profile: background image, interface transparency, blur under panels, background dimming, mode (light / dark) and accent colour.

Property	Value
Type	string (key=value pairs separated by semicolons)
Encoding	UTF-8 or Base64 (base64: prefix)
Applies to	the active profile (primary, or otherwise selected)

Parameter	Values	Description
image	URL (http, https)	Background image
transparency	5–85 (%)	Interface transparency
blur	0–30 (px)	Blur under panels
dim	0–80 (%)	Background dimming
mode	auto, light, dark	Appearance mode. auto follows the background image, or the system theme without one
accent	#RRGGBB or auto	Accent colour. auto picks it from the background image

Every parameter is optional. A parameter missing from the header comes from the user’s own settings. Numbers outside their range are clamped to the nearest bound; unknown parameters and invalid values are ignored.

Image:

• Formats: JPEG, PNG, WebP (JPEG recommended).
• Recommended size: about 1920×1080 and no more than ~2 MB — the image is downloaded every time the theme is applied.
• If the URL contains ;, encode it as %3B.

Full example:

pxd-theme: image=https://cdn.example.com/theme/bg-1920x1080.jpg; transparency=30; blur=4; dim=20; mode=dark; accent=auto

Only a fixed accent colour and a fixed mode, without an image:

pxd-theme: mode=light; accent=#1f9e7a

Here the background stays whatever the user chose; the profile sets the mode and the accent colour.

The same header in Base64:

pxd-theme: base64:bW9kZT1saWdodDsgYWNjZW50PSMxZjllN2E=

Parameters set by the profile are shown in the Theme dialog and cannot be changed there. The user can turn the profile theme off with the “Profile theme” switch in the same dialog, which brings back their own settings. Switching to a profile without this header also brings back the user’s settings (or the defaults if they never changed them). If the header disappears on the next subscription update, the profile theme is removed.

---

HWID Authentication

Prizrak-Box supports the RemnaWave HWID Device Limit header format. When a subscription uses hardware-based device authentication, two groups of headers are involved: headers sent by the client with every request, and headers returned by the server in the response.

Headers Sent by Prizrak-Box (Request Headers)

When a profile has HWID active, Prizrak-Box automatically attaches the following headers to every subscription fetch:

Header	Description
X-Hwid	Hardware fingerprint — the unique identifier for this device
X-Device-OS	Operating system name (e.g. Windows, Android, iOS, macOS)
X-Ver-OS	OS version string (e.g. 14, 11, 14.5)
X-Device-Model	Device model name (e.g. Pixel 8, iPhone 14 Pro Max)

Headers Returned by Server (Response Headers)

The server returns the following headers to communicate HWID status. Prizrak-Box reads and acts on each of them.

X-Hwid-Active

Always true when the HWID Device Limit is enabled on the server side. Prizrak-Box uses this to mark the profile as HWID-protected in the UI.

Property	Value
Type	string (boolean)
Values	true

X-Hwid-Active: true

X-Hwid-Not-Supported

true if HWID Device Limit is enabled on the server, but the client did not send an X-Hwid header. This signals to the app that the device was not identified and the subscription may be restricted.

Property	Value
Type	string (boolean)
Values	true

X-Hwid-Not-Supported: true

X-Hwid-Max-Devices-Reached

true if HWID Device Limit is enabled and the user has reached their maximum number of allowed devices. The app can display a warning to the user that no new devices can be added.

Property	Value
Type	string (boolean)
Values	true

X-Hwid-Max-Devices-Reached: true

RemnaWave compatibility

The HWID header format follows the RemnaWave HWID Device Limit specification. Subscription servers implementing the RemnaWave format are fully compatible with Prizrak-Box.

---

Advanced Templates (PXD) Deprecated

Deprecated — will be removed

The Pxd-Template / Pxd-Template-Scheme header mechanism is deprecated and will be removed from Prizrak-Box in a future release.

How the legacy method worked: How to use xhttp from Remnawave in Prizrak-Box