Featured image of post 🌊 Surgio Tutorial: Make Surge easier

🌊 Surgio Tutorial: Make Surge easier

A tutorial for Surge with Surgio, supporting ssr and v2ray.

🌊 Surgio 使用指導,更洶湧的 Surge(讓你的 Surge 支援 ssr 和 v2ray)

🚨 本文內容由 @jukrb0x 原創撰寫,並首發於本博客。本文僅供學習和使用網絡分析工具 Surge 和開源軟件 Surgio,不得用於其他任何違反您當地法律法規的目的,本文授權使用CC BY-NC-SA 4.0,轉載請註明本文地址。

You can use deepL to translate this document to your language if you can not read English so well.

📜 Introduction

People now tend to have multiple hopping servers in place for the network breakdown, which means that there can be chaotic rules and subscriptions, making a difficult troubshoot of complex networking issues. So here it comes, solving the problem of complex subscription configuration, with just this one simple service you can easily handle with your services. This article provides a comprehensive introduction to Surgio configuring it well in a concise yet easy to understand fashion. To explain it clearly, this article is rather lengthy and if you are a skilled programmer/engineer you should probably visit the official document for a quick start.

Also, this article was written to better configure Surgio. The tricks on external proxy(ssr, v2ray etc.) and rule templates will also be covered accordingly. Generally, you can get the profile of Surge from your airport1. We will focus on customizing the config of Surgio and techniques of using Surge. What’s more, external proxy SSR will be introduced later for Surge and you will know how to configure it easily using Surgio.

Surgio has two main jobs: one that parses the addresses of subscription configurations provided by different airports or a list of nodes maintained by yourself, and the other that generates the specified rules based on templates that you can modify by yourself.2

Install profile from URL
Install profile from URL

🧱 Base

Since you have purchased (or used) Surge as your network diagnostic utility, I believe you have some basic understanding on network and web programming skills. We will skip some simple procedures later.

  • Strong hands-on ability
  • Javascript programming (at least read and modify)
  • Knowledge to use modern editor
  • Basic knowledge of networking (how a simple web server works)
  • Basic knowledge of Git and Github
  • If you are lacking of these abilities, STFW.

💡 Get started

Composition of Surgio

The workflow of Surgio is composed of three main parts.3 To understand the theory of Surgio, understand the relationship of these three components along with the following practice.

✈️ Provider

The provider of server nodes, which can be a subscription address or a configuration of a group of nodes.

📘 Template

A set of rules, Surgio will render files according to the specified template.

💎 Artifact

Artifacts are generated by Surgio based on configurations consist of template and provider.

Install Nodejs

Install the latest Nodejs (LTS) from the official website (skip if you already have one)

To determine if Nodejs works correctly:

$ node -v
v12.18.4 # you may have the diff version from me

Use modern editor to modify the file if any one comes up. If you are a Windows user, be sure to avoid using the default text editor.

Install Surgio

Initialise Surgio with the name my-rule-store which you can designate any name you want

npm init surgio-store my-rule-store

We don’t need to use Aliyun OSS, just check it with [n].

Directory of the project would look like this after install:

├── node_modules
├── package-lock.json
├── package.json
├── provider
├── surgio.conf.js
└── template

Test local generator

You should already have some policy templates after install. To generate a policy group configuration, run this command in the directory.

npx surgio generate

The config files will be added to directory dist in the root of project, if the directory doesn’t exist, it will be created. These configurations are generated by the rules you designated in surgio.conf.js. You can always generate artifacts by inputting the command on your computer according to your config of Surgio.

⚙️ Rules, templates

To most utilize Surgio, we need to configure it right by using templates. Let’s do it.

Surgio has well-established templates for different tools, and we will focus on the configuration of Sugre. You can easily understand the language when you take a quick look at template/surge_v3.tpl . And even better is snippets are provided here so you can implement them on different templates, which improves reusability greatly.

Tree of template directory would be like:

├── clash.tpl
├── quantumult.tpl
├── quantumult_rules.tpl
├── quantumultx.tpl
├── quantumultx_rules.tpl
├── quantumultx_subscribe.tpl
├── shadowsocks_subscribe.tpl
├── snippet
│   ├── apple_rules.tpl
│   ├── blocked_rules.tpl
│   ├── direct_and_domestic_rules.tpl
│   ├── direct_rules.tpl
│   ├── new_apple_rules.tpl
│   ├── nowe_rules.tpl
│   ├── proxy_rules.tpl
│   ├── us_rules.tpl
│   └── youtube_rules.tpl
├── surge_simple.tpl
├── surge_v3.tpl
└── surge_v4.tpl

A ready-made template

I have modified the template provided by N3RO. You can find them in this repository. 🎃

You can find more surge rules on Github, and change them into Surgio templates yourself.

Surge context menu
Surge context menu

👀 ​Sometimes your airport doesn’t provide a surge profile since shadowsocksr and v2ray are not natively supported in Surge, in which case we need to generate one ourselves and only the SSR or v2ray subscription link will suffice. And… External proxy will be introduced here. 💡

External proxy (ssr, v2ray)

External proxy4 is a new feature introduced in Surge Mac Build 6225, it allows Sugre working with other proxy services such as shadowsocksr(ssr), we will see how to make it fly on Surgio.

I am only introducing shadowsocksr(ssr) here, if you are v2ray user please refer to this link, the procedure is the same. First of all you will install a ssr service named shadowsocksr-libev.

Download through this link and put in /usr/local/bin/ssr-local, or you can simply install by the command (that’s better):

curl -L -o /usr/local/bin/ssr-local && chmod +x /usr/local/bin/ssr-local

Configure for Sugrio

To generate artifacts accordingly, add the following fields to surgio.conf.js.

module.exports = {
  // ...
  binPath: {
    shadowsocksr: '/usr/local/bin/ssr-local', // If you are a SSR user
    v2ray: '/usr/local/bin/v2ray' // If you are a V2ray user
  surgeConfig: {
    resolveHostname: true

And change the artifacts, for example:

artifacts: [
  // ...
    name: 'Surge_example_artifact.conf',
    template: 'surge_v4',
    provider: 'feynman_diagram'

☁️ Run on the cloud

We will demonstrate how to run it on a serverless service named Vercel, if you try it only on your computer, you may skip this chapter. 🚨 Nota Bene: Please read carefully if you have any plan on running it on a server in the future.

Set up gateway

Make sure it can run as a http server, you will set up a gateway for this.

This is package.json, which contains the information of dependencies, you won’t see "@surgio/gateway": "^1.2.1" in your package.json ,so please add it to your file and save it.

  "name": "my-rule-store",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "update": "surgio generate && surgio upload"
  "engines": {
    "node": "^12"
  "dependencies": {
    "@surgio/gateway": "^1.2.1",
    "surgio": "^2.7.3"

After modifying package.json, run npm i on the terminal to make sure it will work.

The gateway will be used for communication authorization between local and server later when we run Surgio on Vercel, if you stick to locally then you will no need to add gateway or npm install it, that’s fine.

Or you can install it simply by the command

npm install @surgio/[email protected]^1.2.1 --save

To clarify, the version of node environment should be higher than 12, the surgio I use is v2.7.3 that is the latest version available (as is surgio gateway). If there are updates please let me know, you should follow the instructions from the official documentation before I update this article.

Set up authorization

To prevent your servers from being compromised, please set up authorization for gateway.

// Auth
gateway: {
    auth: true,
    accessToken: 'Password',

Add code above to your surgio.conf.js , under module.exports , as the same level with analytics .

Set up a gateway authorization
Set up a gateway authorization

Configure assessToken as the password you want, it will be used for anthorization between local and server.

Vercel configuration

We will run Surgio on Vercel later, so we will configure a file named vercel.json in your the root directory of project, create one if it doesn’t exist.

Paste the config below to your vercel.json .

  "public": false,
  "builds": [
      "src": "/gateway.js",
      "use": "@vercel/node",
      "config": {
        "includeFiles": ["provider/**", "template/**", "*.js", "*.json"]
  "routes": [
      "src": "/(.*)",
      "dest": "/gateway.js"

Just ignore the "use": "@vercel/node" , we didn’t talk about installing vercel on your computer and yet we don’t need it, of course, you can install one by yourself.

Push to Github

When you finish the basic settings, try to push the project to a Github private repository.

🌙 Make sure it’s only private, ohterwise you may expelled from your airports due to regulations.

As we talked earlier, we won’t introduce and demonstrate the basics and operations related to using Github.

Vercel is an amazing serverless provider, you may use other akin services such as Netlify. 💡 Remember, this tutorial is based on Vercel, if you use other services, please read carefully the documentations and change configurations by yourself.

You won’t need to change the settings on Vercel, just import the project from Github. I’m sure you’ll complete these steps superbly since you can read to this line.

Worth saying, Vercel will deploy your project every time you push the latest commit. 💡 Check out your Vercel project domains, you need to change the urlBase in surgio.config.js after linking to Vercel.

change the example to yours
change the example to yours

This url will be regarded as the prefix of subscription config, that will make sure your Surge syncing profiles from the designated address.

Login to your Surgio

Everything is perfect now, you can access it from the url given by Vercel. You will see an authorization soon. And you can generate the artifact later on the dashboard, to import it to your Surge.

🕶️ Epilogue

The contents of this article are originally written by @jukrb0x and first published in this blog. This article is for the sole purpose of learning about and using the networking analysis tool Surge and open source software Surgio, and should not be used for any other purpose that is contrary to your local laws and regulations, this article is LICENSED UNDER CC BY-NC-SA 4.0. Please note the url of this article for reproduction.

That’s the wrap, thanks for reading. 💃 🌓 🕺

The friends, S10E12
The friends, S10E12

  1. Airport means your servers’ provider that will be mentioned throughout the rest of this article. ↩︎

  2. From the official website of Surgio: link ↩︎

  3. From the official documentation: link ↩︎

  4. external type (Surge Mac only), Official Guidance: Understanding Surge ↩︎

  5. Surge Mac New Features: External Proxy Provider, Yachen Liu, Jul 13 2018, link ↩︎