Sable Documentation

Feature Walkthrough

A plain-language tour of what the app does, so you can find your way around before touching any code. Nothing in this section needs programming knowledge — the technical setup starts at section 1.

First launch and sign-in

• Sign in — email and password, or Google. New users create an account with their email; the backend emails a one-time code to confirm it. A forgotten password is reset the same way.
• Device limit — each plan allows a number of devices at once (1 on Free, 5 on Premium by default). When the limit is reached, the user is asked to sign out another device first.
• Maintenance and updates — if you turn on maintenance mode or require a newer app version in the admin panel, users see that message at launch.

Connecting

• One-tap connect — the Home screen has a large connect button. Once connected it shows the connection time, upload and download speed and the data used.
• Locations — users search locations, see recent and favourite servers and each server's current load. Each location is Free, Ads (unlocked by watching an ad) or Premium.
• Protocol — WireGuard, V2Ray (VMess over TLS) or Auto, which lets the app choose.
• Light and dark theme — the whole app follows the system setting or the user's choice.

Free time, rewarded ads and Premium

• Daily free time — Free users get a daily allowance of VPN time (60 minutes a day by default).
• Rewarded ads — users watch a short ad to add time or to unlock an Ads location. Each step on the reward ladder adds more minutes. The backend adds the time only after AdMob confirms the ad was watched.
• Premium — monthly or yearly subscriptions through Google Play and the App Store (via RevenueCat): all locations, no ads, more devices and no time limit. Users can restore purchases.
• Promo codes — codes you create in the admin panel give a plan for a set time.

Tools

• Speed test — measures latency, jitter, download and upload speed through the tunnel.
• Split tunneling — on Android, users choose apps that skip the VPN. On iOS, they choose domains, because iOS does not allow per-app splitting.
• Kill switch — on iOS, a setting in the app blocks traffic when the VPN drops. On Android, the app guides users to the system's Always-on VPN setting.

Account and settings

Current plan, change password, signed-in devices (sign any of them out), theme, language (English, Bangla, Arabic, Russian and Ukrainian), support messages, debug logs, legal pages, sign out and delete account.

What you control from the admin panel

Almost everything users see is managed in the browser, without rebuilding the app: VPN servers and regions, plans and store products, promo codes, rewarded-ad rules, announcements, push notifications, minimum app version and maintenance mode, the privacy policy, terms and about pages, app users, support messages and integration keys. The full list is in section 14.

Third-Party Services and Costs

Sable is self-hosted: you receive the full source code, with no licence keys and nothing payable to us. Some features connect to outside services that are not included in the purchase.

How the Pieces Connect (Architecture)

Sable is three projects plus one small agent on every VPN server. Only the backend talks to the database and holds secrets. The app never sees another user's data, and the admin panel never talks to PostgreSQL directly.

1. Prerequisites

Use these versions for the smoothest build. The project was built and tested with the versions marked "tested".

Server size

You need two kinds of server: one for the backend and admin panel, and one or more for VPN traffic.

Building the admin panel (npm run build) needs about 1.5 GB of free RAM; on a 2 GB server add swap first. Shared hosting (cPanel without SSH and Node.js) is not enough; you need VPS or cloud servers with root SSH access.

2. Environment Setup

Select your operating system to see the setup steps.

Open and run the app

cd sable-vpn
flutter pub get
flutter run                 # on a connected real device

Before the app can sign in and connect, point it at your backend (section 8). There is no code generation step: translations and models are plain Dart files.

To check the project builds cleanly:

flutter analyze
flutter test

3. Change Package Name and Bundle ID

Every app needs a unique identifier, for example com.yourcompany.vpn. The defaults are com.sablevpn.app (Android and iOS), com.sablevpn.app.VpnTunnel (the iOS tunnel extension) and the App Group group.com.sablevpn.app. Change them before you set up Firebase, because Firebase apps are registered by this identifier.

Android

The change_app_package_name tool in dev_dependencies can do most of the Android part: dart run change_app_package_name:main com.yourcompany.vpn. Check the widget actions afterwards.

The VPN plugin in packages/flutter_vpncore has its own ID, com.sablevpn.core. It is internal and does not need to change.

iOS

Open ios/Runner.xcworkspace in Xcode and change the Bundle Identifier on Signing & Capabilities for both targets:

• Runner → for example com.yourcompany.vpn
• VpnTunnel → the Runner ID plus .VpnTunnel, for example com.yourcompany.vpn.VpnTunnel

Then update the same values in code. The app and the tunnel extension share data through the App Group, and the app starts the tunnel by its bundle ID. If any of these values differ, the app still builds but Connect fails on the device:

Use group. followed by your Runner bundle ID as the new App Group, and register it in your Apple Developer account (section 12).

4. Firebase Setup

Firebase provides Google sign-in, push notifications, Analytics and Crashlytics. It is optional: without it the app runs with email sign-in, and the Google button, push, Analytics and Crashlytics are switched off automatically.

Step 1: Create a Firebase project

• Open the Firebase console and click Create a project. Enter a name and accept the terms.
• Choose whether to enable Gemini, and enable Google Analytics if you want the in-app Analytics, then click Create project.

Step 2: Connect the app (FlutterFire CLI)

Change the package name and bundle ID first (section 3). The FlutterFire CLI then registers your Android and iOS apps and writes the config files:

npm install -g firebase-tools
firebase login
dart pub global activate flutterfire_cli
cd sable-vpn
flutterfire configure --project=<your-firebase-project-id>

Select android and ios and confirm your IDs. The command updates lib/firebase_options.dart, android/app/google-services.json, ios/Runner/GoogleService-Info.plist and firebase.json. The Android build turns on the Firebase and Crashlytics Gradle plugins by itself once google-services.json no longer contains placeholders.

Step 3: Enable sign-in methods

• Open Build > Authentication > Sign-in method and enable Google. (Email sign-in does not use Firebase; the Sable backend handles it.)

Step 4: Service account for the backend

The backend checks Google sign-ins and sends push notifications with a Firebase service account: Project settings > Service accounts > Generate new private key. Paste the JSON in the admin panel (Settings > Integrations) or put it in the backend .env (section 13, step 7).

5. Social Sign-In and Push Notifications

Google

• Enable Google in Firebase Authentication (section 4, step 3).
• Android: add your SHA-1 and SHA-256 fingerprints in Project settings > Your apps > Android: the debug key, your upload key and, after publishing, the App signing key from Play Console. Get local fingerprints with cd android && ./gradlew signingReport. Without them sign-in fails with error 10. Download google-services.json again afterwards.
• iOS: in ios/Runner/Info.plist, replace YOUR_IOS_CLIENT_ID in two places with the iOS client ID from GoogleService-Info.plist: the GIDClientID value (<id>.apps.googleusercontent.com) and the URL scheme com.googleusercontent.apps.<id> (the REVERSED_CLIENT_ID).

Apple

Apple's App Review Guideline 4.8 asks apps that offer a third-party sign-in such as Google to also offer an equivalent private sign-in option. Email and password sign-in is available in Sable; check the current guideline before you submit and be ready to explain your sign-in options to App Review.

Push notifications

• Android: works once google-services.json is in place and the backend has the service account. Notifications use the channel high_priority_channel.
• iOS: in Xcode select the Runner target > Signing & Capabilities > + Capability > Push Notifications (Remote notifications background mode is already set in Info.plist). Create an APNs key in your Apple Developer account and upload it in Firebase: Project settings > Cloud Messaging > Apple app configuration.
• The app registers each device's push token with the backend, and the admin panel sends to those tokens. There is no topic name to keep in sync.

6. Change App Name

Tip: search lib/, android/app/src/, ios/ and packages/flutter_vpncore/ for Sable to find every user-visible occurrence.

7. App Icon, Splash, Colours and Font

App icon and splash

All launcher icons, the notification icon and the splash image are generated from one picture, assets/brand/sable_silhouette.png:

• Replace assets/brand/sable_silhouette.png with your own logo (a PNG with a transparent background, the same pixel size as the original).
• Run flutter test tool/generate_brand_icons.dart. It writes the Android mipmap-* icons, launch_image.png and the ic_stat_sable_logo notification icons, and the iOS AppIcon.appiconset and LaunchImage.imageset.
• The icon and splash background colour is #16408C, set in android/app/src/main/res/values/colors.xml (splash_primary) and res/values/ic_launcher_background.xml. Change both to your brand colour before you generate.
• The animated start screen in the app is lib/design/brand/sable_boot_artwork.dart; the logo mark is lib/design/brand/sable_mark.dart.

Brand colours

All app colours are in lib/design/tokens/sable_colors.dart, with a light set (SableColors.light) and a dark set (SableColors.dark). Flutter writes colours as 0xAARRGGBB: FF (fully opaque) followed by the normal hex code.

// lib/design/tokens/sable_colors.dart
// SableColors.light
primary: Color(0xFF16408C),        // brand blue #16408C
connected: Color(0xFF1D50B5),      // the connect dial when connected

// SableColors.dark
primary: Color(0xFF5B8DEF),        // brand blue for dark mode #5B8DEF
connected: Color(0xFF6FA0FF),

Example: to use orange #FF6B00, change the light primary to Color(0xFFFF6B00) and pick a lighter orange for dark mode, then stop the app and run it again (hot reload does not update const colours). Screens read colours only from this file; a test (test/design/tokens_test.dart) fails if a screen uses a hard-coded colour.

Font

The app uses Inter Tight through the google_fonts package, which downloads the font the first time the app opens. On networks that block Google Fonts the app falls back to the system font. To ship the font inside the app instead, add the font files under flutter: fonts: in pubspec.yaml and change face in lib/design/tokens/sable_typography.dart to use fontFamily.

8. Connect the App to Your Backend

Set your backend address in lib/core/config/auth_api_config.dart:

// lib/core/config/auth_api_config.dart
static const String origin = String.fromEnvironment(
  'AUTH_API_BASE_URL',
  defaultValue: 'https://api.your-domain.com',   // ← your backend, origin only
);

Enter the origin only (no /api/v1); the app adds /api/v1/... itself. You can also leave the file alone and pass the address when you build: --dart-define=AUTH_API_BASE_URL=https://api.your-domain.com.

Other build-time settings

All of these are optional. Pass them with --dart-define=NAME=value, or put them in a secrets.json file (ignored by Git) and build with --dart-define-from-file=secrets.json. A missing value turns that feature off.

Everything else the app needs (plans, locations, ad units, RevenueCat keys, maintenance mode, minimum version, announcements, legal pages) comes from the backend at run time and is set in the admin panel.

9. Languages

The app ships with English, Bangla, Arabic, Russian and Ukrainian. Users pick a language on Account > Language; the app starts in English until they do.

What a language entry looks like

All texts live in one Dart file, lib/core/i18n/app_strings.dart. The keys are in lib/core/i18n/string_keys.dart. Each key has one line per language:

// lib/core/i18n/app_strings.dart
StringKeys.profile: {
  "en": "Profile",
  "bn": "প্রোফাইল",
  "ar": "ملف شخصي",
  "ru": "Профиль",
  "uk": "Профіль",
},

To change a text, edit its line. A missing translation falls back to English for that key only.

Add a language

Example: adding French (fr).

1. In app_strings.dart, add 'fr' to AppStrings.supported, and add a case for 'fr' in _getLocal().
2. Add "fr": "..." to every entry in localStrings in the same file:

   StringKeys.profile: {
     "en": "Profile",
     ...
     "uk": "Профіль",
     "fr": "Profil",
   },

3. In lib/features/preferences/bloc/locale_cubit.dart, add an entry for French to languages (the code and the name shown in the picker, Français).
4. In lib/app/app.dart, add Locale('fr') to supportedLocales.

Remove a language

Do the same steps in reverse: remove the code from AppStrings.supported, _getLocal(), LocaleCubit.languages and supportedLocales. The extra lines in localStrings can stay; they are simply not used.

Default language

English is the default in three places: languageCode = 'en' in app_strings.dart, and the starting value and fallback in locale_cubit.dart. Change all three to start in another language.

10. AdMob and Rewarded Ads

Free users watch rewarded ads to add VPN time or unlock Ads locations; you can also show banner and interstitial ads. The package contains only Google's official test IDs (publisher ca-app-pub-3940256099942544), so ads show "Test Ad" until you add your own. Debug builds always use test ads.

Step 1: App IDs (built into the app)

Create your app in AdMob and replace Google's sample app IDs:

Step 2: Ad unit IDs (in the admin panel)

Create a Rewarded ad unit (and optionally Banner and Interstitial units) for each platform. Then in the admin panel open Plans & billing > Rewarded ads and enter the unit IDs. Release builds use these values; no new app build is needed to change them. As a fallback you can also put your Android rewarded unit in liveAndroidRewardedUnitId in lib/core/config/admob_config.dart.

Step 3: Server-side verification (required for rewards)

The backend adds time only after Google confirms the ad was watched. In AdMob, open your Rewarded ad unit > Server-side verification and set the callback URL to:

https://api.your-domain.com/api/v1/webhooks/admob-ssv

The app passes the user's ID and a one-time code with each ad; the backend checks Google's signature and the code before adding time. Optionally restrict which ad units may grant rewards with ADMOB_REWARDED_AD_UNIT_IDS in the backend .env or the ad unit list on the Rewarded ads page.

Reward rules

On Plans & billing > Rewarded ads you set: rewards on or off, the reward ladder (minutes per ad, by default 30, 50, 60, 90 and 120), rewards per day per user and per device (5), the wait between ads, the most time a user can bank (4 hours), banner on or off, interstitial on or off and how often (every 3 connects). The same page shows a log of every reward and why any was refused.

11. Premium Subscriptions (RevenueCat)

Premium is sold as Google Play and App Store subscriptions through RevenueCat. The app buys through the RevenueCat SDK; RevenueCat tells your backend about every purchase, renewal, cancellation and refund through a webhook, and the backend grants or removes Premium. The app never grants Premium by itself.

Step 1: Create the products in the stores

• Google Play Console > your app > Monetize > Subscriptions: create a subscription with base plans, for example a monthly and a yearly one. (Upload a build with billing to a testing track first; Play Console requires it.)
• App Store Connect > your app > Subscriptions: create a subscription group with a monthly and a yearly product.

Step 2: Set up RevenueCat

• Create a RevenueCat project, add your Android and iOS apps and connect them to the stores (Google service-account credentials and the App Store in-app purchase key, as RevenueCat's setup guide describes).
• Import your products and create a current offering with a monthly and a yearly package.
• Copy the public SDK keys (they start with goog_ and appl_).

Step 3: Connect RevenueCat to Sable

• In the admin panel open Settings > Integrations and enter the RevenueCat Android key and iOS key. The app reads them from the backend at start.
• Generate a webhook secret: openssl rand -hex 32. Enter it as RevenueCat webhook secret on the same page (or REVENUECAT_WEBHOOK_AUTH in the backend .env).
• In RevenueCat open Integrations > Webhooks, add https://api.your-domain.com/api/v1/webhooks/revenuecat and set the Authorization header to exactly the same secret.

Step 4: Match the products to your plans

In the admin panel open Plans & billing > Store products. For each store product, enter the exact product ID from the store and choose the plan it grants. The first start created example products (com.sablevpn.app.premium.monthly, com.sablevpn.app.premium.yearly, and sable_primium_subscription:monthly-premium-base-pack / ...:yearly-premium-base-pack for Google Play): change them to your own IDs. For Google Play use the subscriptionId:basePlanId form.

Then check the plans on Plans & billing > Plans: name, price and currency shown on the paywall, devices, limits and features. The example plans use BDT prices; change them to your own currency and prices.

How it works

• The paywall lists the active plans from the backend and buys the matching store product. Users must be signed in to buy, and the purchase is linked to their Sable account.
• After a purchase the app waits for the backend to confirm Premium (usually a few seconds). Restore purchases on the paywall handles reinstalls and new phones.
• Failed webhook events are retried every 10 minutes and can be replayed on Plans & billing > Payment events.
• Keep RevenueCat sandbox switched on in Settings: App Review tests your app with sandbox purchases.
• You can also give Premium without a purchase: on a user's page in the admin panel use Grant premium, or create promo codes.

12. Build and Release

Version number

Set version: in pubspec.yaml (for example 1.0.1+3: version name 1.0.1, build number 3). Android and iOS both read it. Raise the build number for every upload. In Xcode, give the VpnTunnel target the same version and build as the app, or App Store Connect warns that the extension version does not match.

Android: create an upload keystore

macOS / Linux:

keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

Windows:

keytool -genkey -v -keystore %userprofile%\upload-keystore.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias upload

Android: key.properties

Create android/key.properties:

storePassword=<password from previous step>
keyPassword=<password from previous step>
keyAlias=upload
storeFile=<full path to upload-keystore.jks>

android/app/build.gradle already reads this file. If it is missing, release builds are signed with the debug key so they still build — Google Play will not accept those.

Android: build

flutter build apk --release          # APK for direct install / testing
flutter build appbundle --release    # App Bundle for Google Play

The App Bundle is created at build/app/outputs/bundle/release/app-release.aab. Upload it in Play Console.

iOS: Apple Developer setup

The VPN tunnel is an iOS app extension, so iOS needs a paid Apple Developer account and a little more setup than a normal app. In your Apple Developer account (Certificates, Identifiers & Profiles):

• Register an App Group, for example group.com.yourcompany.vpn (the same value you set in section 3).
• Register two App IDs: the app (com.yourcompany.vpn) and the tunnel (com.yourcompany.vpn.VpnTunnel). Enable Network Extensions and App Groups on both, and Push Notifications on the app ID.

Then in Xcode (ios/Runner.xcworkspace), for both the Runner and VpnTunnel targets:

• Signing & Capabilities: choose your Team (automatic signing) and check the bundle ID.
• Check the capabilities: Network Extensions with Packet Tunnel ticked, and App Groups with your group ticked. On Runner, add Push Notifications if you use push.

iOS: build

cd ios && pod install && cd ..
flutter build ipa --release

• The minimum iOS version is 15.6, set in both the Xcode project and the Podfile. Nothing to change.
• The VPN core framework in ios/Frameworks/ is linked only into the VpnTunnel extension. Do not add it to the Runner target.
• Upload build/ios/ipa/*.ipa with Xcode's Organizer or the Transporter app. See Flutter's iOS deployment guide.

Test on a real device

• Android: enable USB debugging, connect the phone and run flutter run --release. Accept the VPN permission dialog on first connect.
• iOS: connect the iPhone, trust the computer, select it in Xcode and press Run. On first connect iOS asks to add a VPN configuration.
• After connecting, open a "what is my IP" website in the phone's browser: it should show your VPN server's address.

13. Backend Setup (NestJS)

The backend lives in sable-backend/. It is a NestJS 11 + TypeORM API on PostgreSQL. The app, the admin panel and the agents on your VPN servers talk only to this API.

Step 1: Install

cd sable-backend
npm ci
cp .env.example .env

Step 2: Create the database

Use PostgreSQL 14 or newer (tested on 17). In psql as a superuser:

CREATE ROLE sable_user LOGIN PASSWORD 'choose-a-strong-password';
CREATE DATABASE sable OWNER sable_user;

The first start creates four extensions: citext, pg_trgm, pgcrypto and uuid-ossp. On PostgreSQL 13 and newer the database owner may create them. If your host refuses ("permission denied to create extension"), run these once as a superuser:

\c sable
CREATE EXTENSION IF NOT EXISTS citext;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS pgcrypto;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

Step 3: Configure .env

Every variable is explained in .env.example. Only the REQUIRED block must be filled in; every optional feature stays off until you configure it. Generate each secret with openssl rand -hex 48.

Useful optional settings:

Step 4: Your admin account

Sable has a single admin account, defined in .env (there is no admin table). Create the password hash and paste the printed line into .env:

npm run admin:hash -- "your-admin-password"

# prints:
ADMIN_PASSWORD_HASH='$argon2id$v=19$m=65536,p=4,t=3$...'

The password needs at least 10 characters. Keep the single quotes: the hash contains $ signs. To change the password later, run the command again, replace the line and restart the backend.

Step 5: First run

npm run start:dev        # development, with auto-reload; API at http://localhost:3001/api/v1

What a successful first run looks like

This is the real output of npm run start:dev on an empty PostgreSQL 17 database, with only the REQUIRED block of .env filled in (Firebase and R2 not configured yet). The run used PORT=3101 because port 3001 was busy on the test machine; yours will show your own port. About 230 lines that list modules and routes are shortened in the middle.

1. Found 0 errors: the TypeScript code compiled.
2. WARN "Unsupported route path": comes from the NestJS router while it converts a catch-all route. It is harmless and can be ignored.
3. WARN CLOUDFLARE_R2_*: normal until you set up R2 (step 6). Only image uploads in the admin panel are off.
4. WARN No Firebase service account: normal until you add it (step 7). Email sign-in still works; Google sign-in and push notifications are off.
5. Partitions ensured: the monthly tables for VPN session history were prepared.
6. Nest application successfully started: success. The API is ready. The migrations already created every table and the default data before this line.

If the output stops with a red error before line 6, compare it with the troubleshooting list below. The most common causes are a wrong database password or port, a database that does not exist yet, and a port that is already in use (EADDRINUSE).

Check it in the browser or terminal

$ curl -s http://localhost:3001/api/v1/health
{"status":"ok","info":{"database":{"status":"up"}},"error":{},"details":{"database":{"status":"up"}}}

$ curl -s http://localhost:3001/api/v1/regions
{"success":true,"data":[{"code":"id-jkt-01","name":"Jakarta","country_code":"ID","city":"Jakarta","flag_url":"https://upload.wikimedia.org/...","latitude":-6.208763,"longitude":106.845599,"access_level":0}]}

A reply like this means the API, the database and the default data all work. Open http://localhost:3001/api/docs in your browser to see the interactive Swagger API docs:

The first start creates every table and this default data:

No app users are created. Sign in to the admin panel with ADMIN_EMAIL and your password once it is running (section 14).

Step 6: Image storage (Cloudflare R2, optional)

• In Cloudflare, open R2, create a bucket and connect a custom domain (for example cdn.your-domain.com) or enable its public r2.dev URL.
• Create an R2 API token with Object Read & Write on that bucket.
• Fill in CLOUDFLARE_R2_ENDPOINT (https://<account-id>.r2.cloudflarestorage.com), CLOUDFLARE_R2_ACCESS_KEY_ID, CLOUDFLARE_R2_SECRET_ACCESS_KEY, CLOUDFLARE_R2_BUCKET, CLOUDFLARE_R2_PUBLIC_URL (https) and optionally CLOUDFLARE_R2_PREFIX (a folder inside the bucket), then restart.

R2 is used for images you upload in the admin panel: push notification images, region flags and pictures in app pages. PNG, JPEG, WebP and GIF up to 2 MB. Without R2 the upload button reports that uploads are not configured; you can still paste https image links instead.

Step 7: Firebase service account (optional)

The backend uses a Firebase service account to verify Google sign-in and to send push notifications. In the Firebase console open Project settings > Service accounts > Generate new private key, then either:

• paste the whole JSON in the admin panel: Settings > Integrations > Firebase service account (takes effect within 30 seconds, no restart), or
• encode it and put it in .env: base64 -i service-account.json | tr -d '\n' → FIREBASE_SERVICE_ACCOUNT_B64=..., then restart.

The service account must belong to the same Firebase project as the app (section 4).

Step 8: Go live with PM2 and nginx

npm ci
npm run build
npm install -g pm2
pm2 start prod.config.js      # app name "sable-api", NODE_ENV=production
pm2 save && pm2 startup        # restart automatically after a reboot

Or run bash scripts/deploy-production.sh, which checks for .env, builds, and starts or reloads sable-api. Keep one PM2 instance: the scheduled jobs (free-time limits, idle sessions, server health, push sending, subscription expiry and clean-up) run inside the process.

Put nginx in front with HTTPS (for example with Let's Encrypt / certbot):

server {
    listen 80;
    server_name api.your-domain.com;
    client_max_body_size 10m;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Then run sudo certbot --nginx -d api.your-domain.com and set TRUST_PROXY=loopback in .env. Release builds of the app only talk to HTTPS addresses.

Troubleshooting

14. Admin Panel Setup (Next.js)

The admin panel lives in sable-admin/. It is a Next.js 16 web app (React 19, Tailwind 4) that talks to the backend. It needs Node.js 20.9 or newer (tested on 24).

Step 1: Install and configure

cd sable-admin
npm ci
cp .env.example .env

Step 2: Run

npm run dev        # http://localhost:5101

Start the backend first. A successful start looks like this (real output):

1. Ready: the admin panel is running at http://localhost:5101.
2. GET /login 200: your browser opened the sign-in page.
3. Environments: .env: your settings file was found. If this line is missing, the panel uses the default backend address http://localhost:3001.
4. Generated AGENTS.md and CLAUDE.md: Next.js 16 writes two helper files for AI coding tools into the project folder on next dev. They are not used by the panel; you can delete them or ignore them.

Open http://localhost:5101. You should see the sign-in page:

After signing in you land on the Dashboard. On a new installation most numbers are 0 until users connect. If sign-in fails with "Cannot reach the server", check that the backend is running and that API_BASE_URL is right.

Step 3: Go live

npm ci
npm run build
pm2 start prod.config.js     # app name "sable-admin", runs "next start" on port 5101
pm2 save

Put nginx in front with HTTPS. HTTPS is required in production: the sign-in cookie is marked Secure, so the browser will not send it over plain HTTP.

server {
    listen 80;
    server_name admin.your-domain.com;
    client_max_body_size 10m;

    location / {
        proxy_pass http://127.0.0.1:5101;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Then run sudo certbot --nginx -d admin.your-domain.com. Vercel also works: import the sable-admin folder, set API_BASE_URL in the project settings and deploy. npm run build downloads the Geist fonts from Google Fonts, so the build machine needs internet access.

Accounts and security

• There is one admin account, set in the backend .env (ADMIN_EMAIL and ADMIN_PASSWORD_HASH). There are no staff roles; the admin can use every page.
• A session lasts one hour by default (ADMIN_TOKEN_TTL_SEC in the backend). When it expires the panel returns you to the sign-in page with "Your session expired".
• Five wrong passwords from one IP lock sign-in for 15 minutes. Use ADMIN_IP_ALLOWLIST in the backend to allow the admin API only from your own IPs.
• Every change made in the panel is recorded in the Audit log with the time, IP and the values before and after.

What you can manage

Admin panel tour

Screenshots from the demo, so you know your way around before you add your own servers. Server addresses are examples.

Account deletion

Apple and Google require that users can delete their account from inside the app. Sable does this in two steps, the common pattern for apps with paid plans: the account is blocked at once, then deleted automatically after a grace period, so a request made by mistake can still be cancelled.

1. The user asks. In the app: Account → Delete account. An email account confirms with its password; a Google account does not need one. The screen says when the account will be deleted and that an app store subscription is not cancelled with it.
2. Blocked at once. Every device is signed out, VPN tunnels close and push notifications stop. Signing in again shows “This account is scheduled for deletion”. In the admin panel the user shows as Deletion requested, with the reason and the deletion date.
3. Deleted automatically. Every hour the backend deletes the accounts whose grace period has passed. Set the period in Settings → Data retention → Account deletion grace period (days): 0 to 30, default 30. With 0 the account is deleted the moment the user asks.
4. Admin options during the grace period. On the user's page: Cancel request (the account is active again, nothing was lost) or Delete permanently (deleted now).

Branding the admin panel

The panel is in English. Dates and numbers follow the browser's language.

Troubleshooting

15. VPN Servers and the Node Agent

Your users' traffic flows through VPN servers that you rent and control. Each one runs WireGuard, optionally Xray for V2Ray (VMess over TLS), and the small Sable node agent, which keeps the server in sync with the backend. You add servers from the admin panel; one copy-and-paste command sets each one up.

What a VPN server needs

Step 1: Add a region

In the admin panel open Regions and add the location: code (for example sg-sin-01), name, country code, city, map position, a flag image, the access level (Free, Ads or Premium) and the sort order. The first start of the backend created an example region, Jakarta, with a placeholder server; edit or delete them.

Step 2: Add the server (the wizard)

Open Servers > Add server. The wizard has five steps:

1. Details — region, display name, hostname, public IPv4, provider, access level, maximum connections and bandwidth. Turn WireGuard on (UDP port 51820) and, if you want, V2Ray (VMess) with its TCP port and TLS.
2. IP pool — the private addresses given to WireGuard clients. The default 10.8.0.0/24 (gateway 10.8.0.1, DNS 1.1.1.1, 1.0.0.1) serves about 250 users at once; use 10.8.0.0/22 for more. This step is skipped when WireGuard is off.
3. Install — the panel creates the server in maintenance mode and shows a one-time install command. The agent token inside it is shown only once; copy the command before you continue.
4. Verify — run the command on the server (step 3). The panel checks every 3 seconds until the agent has reached the API, registered its WireGuard key and sent its first heartbeat.
5. Go live — the panel lists anything still missing. Click Activate server to make it available in the app.

Step 3: Run the install command on the server

SSH into the new server and paste the command from the panel. It looks like this:

curl -fsSL 'https://api.your-domain.com/api/v1/node-agent/install-agent.sh' \
  | sudo bash -s -- --api 'https://api.your-domain.com/api/v1' \
      --server-id '<server id>' --token '<one-time token>'

The script, in order:

• checks it runs as root on a supported system, and installs curl, jq and a few basic tools;
• asks the API for this server's settings (a 401 here means a wrong server ID or token);
• installs Node.js 22 from nodejs.org (checksum verified) if Node.js 20 or newer is missing;
• WireGuard: installs it, creates /etc/wireguard/wg0.conf with a new key and NAT, starts wg-quick@wg0 and registers the public key with the API;
• V2Ray (if enabled): installs Xray-core (checksum verified) as the xray service, gets a Let's Encrypt certificate for the hostname, and blocks traffic to private addresses;
• Agent: installs it in /opt/vpn-node-agent, writes its settings to /opt/vpn-node-agent/.env (readable by root only) and starts the vpn-node-agent systemd service.

It ends with "Agent is running". Back in the panel the Verify step turns green.

Options: --skip-wireguard (V2Ray only), --iface NAME (WireGuard interface name, default wg0), and --insecure-http (allows an http:// API address; only for testing on a private network).

What the agent does

• Every 30 seconds it sends a heartbeat: CPU, memory, load, connected peers and bandwidth. These numbers appear on the Dashboard and the server page.
• Every 5 seconds it asks the API for peers to add or remove, and applies them to WireGuard and Xray. So a user can connect a few seconds after tapping Connect.
• It signs every request with its own agent token. The backend stores only a hash of the token.
• It opens no ports. If a server stops sending heartbeats for 120 seconds, the backend marks it unreachable and stops sending users to it.

Check a server

systemctl status vpn-node-agent                      # should be active (running)
journalctl -u vpn-node-agent -n 30 --no-pager        # no "401" or "failed" lines
wg show                                              # WireGuard interface and peers
systemctl status xray                                # if V2Ray is enabled
certbot certificates                                 # if V2Ray is enabled

Day-to-day operations

To update the agent on a server later, run the update command (no arguments; it reads the existing settings):

curl -fsSL 'https://api.your-domain.com/api/v1/node-agent/install-agent.sh' | sudo bash

Troubleshooting

16. API Reference

All endpoints live under https://api.your-domain.com/api/v1. The full, always-current reference with every request body is the Swagger UI at /api/docs (when SWAGGER_ENABLED is on). This section covers the conventions and the most important calls. The JSON below was captured from a real server or built from the request classes in the code.

Conventions

• Requests and responses are JSON. Uploads use multipart/form-data with a field named file.
• Unknown fields in a request body are rejected with 400 ("property … should not exist").
• IDs are UUIDs. Times are ISO 8601 in UTC.
• Rate limit: 100 requests per 60 seconds per IP by default (THROTTLE_TTL_MS, THROTTLE_LIMIT), with tighter limits on sign-in, codes, connect and promo codes. Admin routes allow 60 per minute. Over the limit you get 429.
• Device headers. auth/signup, auth/login and auth/social require X-Device-Id (a stable ID per install, up to 128 characters) and X-Platform (android, ios, windows, macos, linux or tv). Optional: X-Device-Model, X-OS-Version, X-App-Version, X-App-Build, X-Locale. Other routes take the device from the token.

The response envelope

// success
{ "success": true, "data": { ... } }

// error (real response)
{ "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid credentials" },
  "path": "/api/v1/auth/login", "timestamp": "2026-10-25T10:19:58.275Z" }

// validation error: message is a list (real response)
{ "success": false,
  "error": { "code": "BAD_REQUEST", "message": ["user_name must be an email", "password must be a string"] },
  "path": "/api/v1/auth/login", "timestamp": "2026-10-25T10:19:53.928Z" }

The health check (GET /health) and the agent files (GET /node-agent/:name) are not wrapped. Some errors carry extra fields; for example DEVICE_LIMIT_EXCEEDED includes limit, devices and a device_manage_token the app uses to sign another device out.

Pagination (admin lists): ?page=1&limit=20 (maximum 100). The response data is { "items": [...], "page": 1, "limit": 20, "total": 57 }.

Authentication

App users get a short-lived access token (15 minutes) and a refresh token (30 days). Send the access token on every user request:

Authorization: Bearer <access_token>

Sign-up with an email code:

POST /api/v1/otp/send
{ "destination": "user@example.com", "purpose": "register" }

// real response
{ "success": true, "data": { "sent": true, "resend_in": 60, "resend_available_at": "2026-10-25T10:21:03.488Z",
  "expires_in": 600, "expires_at": "2026-10-25T10:30:03.488Z", "attempts_left": 5 } }

POST /api/v1/otp/verify
{ "destination": "user@example.com", "purpose": "register", "code": "123456" }
// → data: { "otp_token": "...", "expires_in": 900, ... }

POST /api/v1/auth/signup          (device headers required)
{ "otp_token": "...", "password": "Str0ng!Passw0rd", "full_name": "Demo User" }
// → 201, same body as login below

Password reset uses the same two code calls with "purpose": "reset_password", then POST /auth/reset-password with { "otp_token", "new_password" }.

Login:

POST /api/v1/auth/login           (device headers required)
{ "user_name": "user@example.com", "password": "Str0ng!Passw0rd" }

{ "success": true, "data": {
  "access_token": "eyJ...", "refresh_token": "...", "expires_in": 900,
  "expires_at": "2026-10-25T10:15:00.000Z", "refresh_expires_at": "2026-11-24T10:00:00.000Z",
  "user": { "id": "uuid", "user_name": "user@example.com", "full_name": null,
            "register_provider": "email", "has_password": true },
  "device": { "device_id": "uuid", "login_provider": "email" },
  "entitlement": { "plan_code": "free", "plan_name": "Free", "access_level": 0, "max_devices": 1,
                   "data_limit_bytes": null, "data_limit_period": "month", "speed_limit_mbps": null,
                   "session_limit_seconds": 3600, "shows_ads": true, "source": "free", "expires_at": null } } }

Other auth calls: POST /auth/social with a Firebase ID token (Google), POST /auth/refresh with { "refresh_token" } (a reused refresh token signs that device out), POST /auth/logout, GET/PATCH /auth/me, POST /auth/change-password and POST /auth/delete-account.

Admins sign in separately; admin and user tokens are signed with different secrets and cannot replace each other:

POST /api/v1/admin/auth/login
{ "email": "admin@your-domain.com", "password": "your-admin-password" }

// real response
{ "success": true, "data": { "access_token": "eyJ...", "expires_at": "2026-10-25T11:18:39.285Z" } }

Example: connect

POST /api/v1/connect              (user token)
{ "region_code": "id-jkt-01", "protocol": "wireguard", "supported_protocols": ["wireguard", "v2ray"],
  "credentials": { "wireguard": { "public_key": "<the app's WireGuard public key>" } },
  "idempotency_key": "c0ffee-1" }

{ "success": true, "data": {
  "session_id": "uuid", "protocol": "wireguard", "peer_ready": false,
  "config": { "address": "10.8.0.2/32", "dns": ["1.1.1.1", "1.0.0.1"], "mtu": 1420,
              "peer": { "public_key": "<server key>", "endpoint": "jkt01.your-domain.com:51820",
                        "allowed_ips": ["0.0.0.0/0", "::/0"], "persistent_keepalive": 25 } },
  "session": { "started_at": "...", "expires_at": "...", "limit_seconds": 3600 },
  "server_time": "..." } }

Send "protocol": null to let the backend choose (Auto). For V2Ray, config is a VMess client configuration instead. peer_ready becomes true once the server's agent has applied the peer (within about 5 seconds). Errors include REQUIRES_UPGRADE and REQUIRES_AD (location needs Premium or an ad), DAILY_LIMIT_REACHED, DATA_LIMIT_REACHED, NO_SERVER_AVAILABLE, AT_CAPACITY and MAINTENANCE.

Example: plans (public)

GET /api/v1/plans

// real response, shortened
{ "success": true, "data": [
  { "code": "premium_monthly", "name": "Premium Monthly", "access_level": 10, "max_devices": 5,
    "shows_ads": false, "features": ["All server locations", "No ads", "5 devices", "Unlimited session time"],
    "price": { "amount_minor": 50000, "currency": "BDT", "display": "৳500.00" },
    "billing_period_days": 30, "is_recurring": true, "platforms": ["android", "ios"],
    "payment_methods": [
      { "gateway_code": "revenuecat_android", "name": "Google Play", "payment_type": "sdk",
        "product_id": "sable_primium_subscription:monthly-premium-base-pack",
        "charge": { "amount_minor": 200, "currency": "USD", "display": "$2.00" } },
      { "gateway_code": "revenuecat_ios", "name": "App Store", "payment_type": "sdk",
        "product_id": "com.sablevpn.app.premium.monthly",
        "charge": { "amount_minor": 200, "currency": "USD", "display": "$2.00" } } ] } ] }

The plan price and currency are what the paywall shows; the store charge comes from each store product. Change both in the admin panel to match your own store prices.

Endpoint groups

Every path below is relative to /api/v1. Access: public (no token), user (app token), admin (admin token, optional IP allowlist), node (a VPN server's agent token).

17. Database Schema

PostgreSQL 14 or newer, managed with TypeORM. The tables are created by the migrations in sable-backend/src/database/migrations/, which run when the server starts (DB_RUN_MIGRATIONS=true). sable-backend/database/schema.sql holds the same schema and default data if you prefer to create the database by hand.

Conventions

• IDs are UUIDs; times are timestamptz.
• Email addresses use citext, so they are compared without regard to case.
• Lists and settings are stored as jsonb (plan features, protocol settings, app settings, audit before/after).
• vpn_sessions is partitioned by month on started_at. The backend creates the next two months' partitions at start and every night at 02:00.
• Extensions: citext, pg_trgm, pgcrypto, uuid-ossp.

Tables by area

There is no admin table: the single admin account lives in the backend .env.

Key tables

Enum values

Migrations

npm run migration:show       # list applied and pending migrations
npm run migration:run        # apply pending migrations by hand
npm run migration:revert     # undo the last migration

Backups

pg_dump -Fc -d sable -f sable-$(date +%F).dump        # back up
pg_restore -d sable --clean sable-2026-01-15.dump      # restore

Schedule a daily backup (for example with cron) and keep copies off the server. The backend deletes old session and log data after the number of days set on the admin panel's Settings page (30 by default).

18. FAQ and Common Build Errors

Before anything else

• Run flutter doctor and fix every item it reports.
• Run flutter clean then flutter pub get, and try again.

Flutter app

Backend, admin panel and VPN servers

See the troubleshooting tables in section 13, section 14 and section 15.

General questions

19. Support

Questions before or after purchase? Please use the Support tab on the CodeCanyon item page. All support is handled through the official Envato item support system.

Support covers bugs and questions about the included features. Customisation, and installation on your own servers, are not part of item support.

Before you open a ticket

• Check the FAQ and common build errors and the troubleshooting lists in sections 13, 14 and 15.
• Make sure you are on the latest version (see the changelog).

What to include

A complete first message lets us answer in one reply instead of several:

More resources

• Live demo: the admin panel and Android demo app linked on the item page.
• Video tutorials: environment setup for Windows, macOS and Linux (section 2) and Firebase with Flutter (section 4).
• Flutter: docs.flutter.dev · NestJS: docs.nestjs.com · Next.js: nextjs.org/docs · WireGuard: wireguard.com · RevenueCat: revenuecat.com/docs

20. Changelog

Version 1.0.0 (Initial Release)

• Initial release: Flutter VPN app (Android and iOS), NestJS backend with VPN node agent, and Next.js admin panel.

21. Upgrading to a New Version

When a new version of Sable is released, download it from your CodeCanyon Downloads page and read its changelog first. Your users, servers, plans, subscriptions and settings live in your PostgreSQL database, not in the code, so updating the code does not delete them.

Before you start

• Back up the database (see section 17, Backups):

  pg_dump -Fc -d sable -f sable-before-upgrade.dump

• Keep your own changes in Git, or note which files you edited, so you can carry them over.
• Never overwrite these files with the ones from the new package; they hold your settings:

  Project	Keep your copy of
  Backend	.env, and prod.config.js if you changed the PM2 name or memory limit
  Admin panel	.env, and prod.config.js or the port in package.json if you changed them
  Flutter app	lib/firebase_options.dart, android/app/google-services.json, ios/Runner/GoogleService-Info.plist, android/key.properties and your keystore, secrets.json, lib/core/config/auth_api_config.dart, lib/core/config/admob_config.dart, ios/Flutter/*.xcconfig, ios/Runner/Info.plist, your bundle IDs and App Group (section 3), your icons and assets/brand/, and lib/design/tokens/sable_colors.dart

• Compare the new .env.example files with your .env files and add any new variables.

Carrying your own code changes forward

If you edited source files (not only settings), do not copy the new version straight over them. The safest way is Git:

# one time, before your first customisation
cd sable-backend            # or sable-admin, or sable-vpn
git init && git add -A && git commit -m "Sable 1.0.0 original"
# ...make your changes and commit them as usual...

# when a new version arrives
git checkout -b upgrade
# copy the new package files over the folder (keep the files listed above)
git add -A && git commit -m "Sable 1.x.x original"
git checkout main && git merge upgrade      # Git combines both; fix any conflicts it lists

Without Git, compare your old folder and the new one with a diff tool (VS Code: right-click two files > Compare Selected) and re-apply your edits to the new files.

1. Backend

cd sable-backend
# copy the new files over your old folder, keeping your .env
npm ci
npm run build
pm2 reload sable-api

• Database changes are applied automatically. With DB_RUN_MIGRATIONS=true the server runs every new migration when it starts. Each migration runs once and is recorded in the migrations table.
• Migrations keep your existing rows. If a release ever needs to change existing data, its changelog says so.
• Check what ran: npm run migration:show. If something goes wrong, npm run migration:revert undoes the last migration, or restore the backup with pg_restore -d sable --clean sable-before-upgrade.dump and go back to the old code.
• Never edit an existing migration file; add a new one instead (npm run migration:generate).

2. VPN servers

If the changelog mentions the node agent, run the update command on each VPN server (section 15). It keeps the server's settings and token.

3. Admin panel

cd sable-admin
# copy the new files over your old folder, keeping .env
npm ci
npm run build
pm2 restart sable-admin

The admin panel stores nothing itself; all data comes from the backend. Upgrade the backend first.

4. Flutter app

• Copy the new lib/, packages/, assets/ and pubspec.yaml over your project, then restore the files you customised (list above). If you use Git, commit first and review the diff.
• Run:

  flutter clean
  flutter pub get
  cd ios && pod install && cd ..
  flutter run

• Raise version: in pubspec.yaml (for example 1.0.1+2) and publish the update as in section 12.
• Old app versions keep working with the new backend unless the changelog says otherwise. To make everyone update, raise the minimum version on the admin panel's App config > Versions page.

22. Open-Source Licences

Each adapted file carries a header naming its source. The full notices are in sable-vpn/NOTICE and the licence text in sable-vpn/LICENSE-GPL-3.0.

What this means for you

Because the app links this core, the Flutter app (sable-vpn/) is licensed under GPL-3.0-or-later (see sable-vpn/LICENSE.md). You may use, change and publish it, commercially too. When you distribute it (for example on Google Play or the App Store) you must:

1. Make the complete corresponding source code of the app you distribute available to its users under GPL-3.0-or-later, as a public repository link or a written offer valid for at least three years.
2. Include the GPL-3.0 licence text and the notices. The app's About us page is seeded with this notice and a source-code request address: in the admin panel open App config → Pages → About us and replace support@example.com with your own address. You may reword the page, but keep the notice and the way to get the source.
3. Not add terms that restrict your users' GPL-3.0 rights.
4. Not name your app after sing-box or suggest any association with it.

The backend and the admin panel do not include sing-box; they are licensed under the Envato Market licence you purchased, which adds no restriction to the app's GPL-3.0 rights. This section is a summary, not legal advice; if you are unsure, ask a lawyer before you publish.

Other libraries

The app, backend and admin panel install their other libraries from pubspec.yaml and package.json; each keeps its own licence (mostly MIT, BSD and Apache 2.0).

The VPN servers use WireGuard and Xray-core, which the install script downloads from their official sources onto your server; they are not part of the package.

The sable silhouette used in the logo is by Margot Michaud, published under CC0 (public domain) on PhyloPic.

23. AI Disclosure

AI tools were used to help create parts of this item:

• Code: AI-assisted writing and review of source code in the app, the backend and the admin panel.
• Documentation and description: this documentation, the README files and the item description were written and edited with AI assistance.
• Graphics: the preview images and screenshots were edited with AI tools.

All of it was reviewed, tested and finished by the author.

The item has no AI features: the app, the backend and the admin panel do not use or call any AI service or model.