Skip to content

Getting Started

Jump to bottom
Next1971 edited this page Oct 17, 2026 · 3 revisions

Getting Started

MASQUE VPN is an experimental, self-hosted VPN. You need your own Linux VPS and a separate client profile for every device.

This guide covers the published v2.1.0 release and iOS 2.0 on TestFlight. For exact commands and configuration formats, use the documentation matching the release you deploy.

1. What you need

  • A Linux VPS with a public address and /dev/net/tun.
  • Administrative access to configure the service, forwarding, and firewall.
  • Permission to allow the selected port in both the VPS firewall and the provider's cloud security group.
  • An Android phone, Android TV device, Windows PC, or a physical iPhone.
  • A secure way to transfer client credentials.

Traffic exits at your VPS. The project does not provide public servers or a commercial VPN subscription.

2. Install the server

Use the server installation guide.

Available paths:

Path Notes
Manual Linux installation Review and run the server-side steps yourself
install.sh Fresh Ubuntu/Debian installation; verifies release checksums and refuses to overwrite an existing installation
Docker Compose Experimental; requires host networking, NET_ADMIN, and /dev/net/tun
Windows VPS Setup Helper Experimental SSH deployment from Windows using masque-setup.exe and a matching Linux server binary

Download server files from v2.1.0.

The Windows helper does not contain the Linux server binary. Put vpn-server-linux-amd64 or vpn-server-linux-arm64 beside the EXE, matching your VPS architecture.

Do not run a fresh-install procedure over a working server just to update its binary. Preserve the CA, certificates, profiles, and configuration.

3. Allow both transports

The server uses the same port number for two separate transports:

  • UDP: HTTP/3 CONNECT-IP over QUIC.
  • TCP: HTTP/2 CONNECT-IP over TLS.

Allow UDP and TCP separately in both firewalls if you want both transports.

A TCP connection may display an HTML page without granting VPN access. The page is not an installation or authentication test. Because the server certificate uses a private CA, a normal browser shows a certificate warning.

4. Issue a profile for each device

Follow the client configuration guide.

Use a separate profile.masque bundle for every device. Do not connect multiple devices with the same active profile.

A real profile includes a client private key:

  • Transfer it privately.
  • Do not upload it to an issue or public chat.
  • Do not commit it to Git.
  • Treat a QR code containing the profile as credentials too.

Back up the server's CA securely.

5. Install a client

Android phone

  1. Install masque-phone-2.1.0.apk.
  2. Import the device's profile.masque.
  3. Grant VPN permission.
  4. Allow the battery-optimization exemption if requested.
  5. Connect.

See the Android guide.

Android TV

Install masque-tv-2.1.0.apk.

Use Paste config from clipboard or paste-text import. Transfer the complete profile privately and clear credential-bearing clipboard contents where possible.

Windows

  1. Install masque-2.1.0.msi and approve the installation UAC prompt.
  2. Open MASQUE VPN from the Start menu as a normal user.
  3. Import the device's profile.masque.
  4. Connect.

Closing the GUI does not disconnect the tunnel. Use Disconnect.

See the Windows guide.

iOS

Install iOS 2.0 through TestFlight, import a device-specific profile, and allow VPN configuration.

No IPA is attached to GitHub Releases. Check the current build and expiry in TestFlight.

See the iOS guide.

6. Start with the default settings

Android, Android TV, and Windows v2.1.0 provide:

  • Automatic / UDP only / TCP only.
  • Configurable tunnel MTU, default 1340.
  • Optional kill switch, off by default.
  • Day/month traffic statistics.

Start with Automatic and MTU 1340. Use explicit UDP-only and TCP-only tests when diagnosing a connection.

Do not assume iOS has identical controls merely because it supports both transports.

7. Verify the connection

Check all of the following:

  1. The client establishes an authenticated VPN connection.
  2. The public exit address matches the VPS.
  3. DNS resolution works.
  4. Websites and other required applications work.
  5. Reconnection works after a network change.
  6. IPv6 behaves as intended if you use it.

A connected status or visible TCP website alone is not sufficient.

Compatibility

Existing profiles and certificates remain unchanged in v2.1.0.

  • Older UDP clients can use the v2.1.0 server over UDP.
  • TCP requires a v2.0.0 or v2.1.0 server.
  • v2.1.0 clients can use older servers over UDP.
  • iOS 2.0 supports UDP and TCP with the current server.
  • Older iOS 1.7 is UDP-only.

Next pages

Clone this wiki locally