VPN setup guides for Android, iPhone and desktop

The task

A person with no technical background who has just received a VPN subscription needs a clear “what to tap” guide for their own device. Without one, they write to support with the same questions every time: where to get the app, how to add the subscription, how to switch the VPN on. Each such question is a load on whoever supports the service.

Users' devices vary: phones on Android, iPhone and iPad, computers on Windows, macOS and Linux. Each platform has its own client and its own menu items. The guide has to be separate for each, short, and available where the person already is: in the chat with the service's bot in Telegram.

The solution

A set of five static HTML pages, one per platform. The pages are designed to open inside a Telegram Mini App from the service's bot. What is implemented, per the README:

• Five self-contained pages: Android, iPhone and iPad, Windows, macOS and Linux, each with steps, hints and a questions block.
• A path from installing the app to switching the VPN on, and a “Not working? Check this” section.
• A link to the service's bot at the start and at the end of every page.
• A “Done, close” button: the page closes and returns the person to the chat.
• Styling that follows the Telegram theme: colors come from the client's variables.
• Publication on GitHub Pages and an open repository on GitHub.

How it works

Static pages with no build step

Each page is one HTML file: the styles and scripts are embedded, and there is no bundler, Docker or environment variables. Such files can be opened with a double-click or served by any static host. A simple server is enough for local viewing. The only external dependency is the Telegram Web Apps script, loaded from telegram.org.

A Telegram Mini App: a page inside the chat

A Mini App (called a WebApp in the source) is a web page that Telegram shows inside the messenger itself. On load the page calls Telegram.WebApp.ready() and expand(): it tells Telegram it is ready and expands to full screen. The “Done, close” button calls Telegram.WebApp.close() and returns the person to the chat. Telegram requires an HTTPS address for a Mini App, which is why the pages are hosted on GitHub Pages. Outside Telegram the Telegram.WebApp object is unavailable and the close button doesn't work there, as expected.

The Telegram theme and a phone layout

The pages take their colors from CSS variables set by the Telegram client, so in both dark and light themes the guide looks like part of the messenger. The layout is designed for a phone screen: per the acceptance criteria, it has to read well on a phone and the colors must follow the theme.

Steps for specific clients

For Android, Windows and Linux the guide walks through the NekoBox client, for macOS it walks through V2Box, and iPhone and iPad have a page of their own. Each page has one scenario: install the app, add the subscription, switch the VPN on, and check if it doesn't work. The file name tells you the platform: android.html, ios.html, windows.html, macos.html, linux.html.

Publishing and checking the pages

No build is needed: the files are placed on any static host over HTTPS and the page addresses are set in the bot. Locally, a page can be opened in a browser or served with a simple python -m http.server. The README's acceptance criteria check five things: the pages open with no console errors, they expand to full screen inside Telegram, the bot link leads to Telegram, the layout reads well on a phone, and the steps match the client's interface. The last item is checked by hand on a device.

Results

• Five platforms are covered by five pages, each independent of the others.
• The pages are designed to be opened from the bot inside Telegram, without switching to a browser.
• The project needs no build step, Docker or environment variables: editing a page means editing one HTML file.
• The repository is open, and the live version is published on GitHub Pages.

Technologies and why

• HTML5, CSS, JavaScript: pages with no build step and no dependencies; styles and scripts are embedded in each file.
• Telegram Web Apps API: full-screen expansion, the close button and the Telegram theme colors.
• GitHub Pages: static hosting over the HTTPS that a Telegram Mini App requires.

Status

In production, an open project of our own. There are no explicit versions: the latest log entry is dated July 28, 2026, when the files were updated through the GitHub web interface. The first upload was on January 21, 2026, and on January 23 the Android, iOS, Linux and macOS pages were expanded and reworked.

Known limitations per the README: the guides are tied to the client menu item names and go stale when the clients update; the bot's address is hardcoded in each of the five files and there is no shared template; there are no automated tests or link checks. The pages also carry copy protection (blocked text selection, context menu and inspector hotkeys): the README calls it decorative, says it hurts accessibility and doesn't protect the content, and suggests removing it or keeping it deliberately.