Surge

Surge is a network toolbox. Protocol Launcher allows you to generate Surge URL scheme links.

Usage

There are two ways to use this library:

• On-Demand import from subpaths enables tree-shaking and keeps bundles small.
• Full Import from the root package is convenient but includes all app modules.

Pick On-Demand for production builds; Full Import is fine for quick scripts or demos.

Select Installation Method

On-Demand

Recommended. Optimized for production.

Full Import

Convenient. Good for quick scripts.

Notes

start/stop/toggle are iOS-only. Configuration/module installation and license activation use surge on iOS and macOS; surgeconfig is a macOS compatibility scheme (Mac 6.7.0+). autoclose is iOS-only and cannot be used with install-config. On iOS, license activation requires no active non-trial license; on macOS, the activation window must already be open. The current reference lists callbacks for start/stop/toggle.

Start

On-Demand

import { start } from 'protocol-launcher/surge'

const url = start()

Start And Auto Close

On-Demand

import { start } from 'protocol-launcher/surge'

const url = start({
  autoclose: true,
})

Stop

On-Demand

import { stop } from 'protocol-launcher/surge'

const url = stop()

Toggle

On-Demand

import { toggle } from 'protocol-launcher/surge'

const url = toggle({
  autoclose: true,
})

Install Config

On-Demand

import { installConfig } from 'protocol-launcher/surge'

const url = installConfig({
  url: 'https://example.com/surge.conf',
})

X-Callback Start

On-Demand

import { xCallbackStart } from 'protocol-launcher/surge'

const url = xCallbackStart()

X-Callback Stop

On-Demand

import { xCallbackStop } from 'protocol-launcher/surge'

const url = xCallbackStop()

X-Callback Toggle

On-Demand

import { xCallbackToggle } from 'protocol-launcher/surge'

const url = xCallbackToggle()

Install Module

Install a module from its URL. The URL is percent-encoded; scheme also accepts surgeconfig for macOS compatibility.

On-Demand

import { installModule } from 'protocol-launcher/surge'

const url = installModule({
  'url': 'https://example.com/example.sgmodule'
})

Email License Activation

Prefill the email-license activation flow.

On-Demand

import { emailLicense } from 'protocol-launcher/surge'

const url = emailLicense({
  'email': 'name@example.com',
  'key': 'REPLACE_WITH_LICENSE_KEY'
})

Team License Activation

Prefill the team-license activation flow. enterprise-license is the canonical route; team-license is an app-side alias.

On-Demand

import { enterpriseLicense } from 'protocol-launcher/surge'

const url = enterpriseLicense({
  'companyID': 'REPLACE_WITH_COMPANY_ID',
  'userID': 'REPLACE_WITH_USER_ID',
  'passcode': 'REPLACE_WITH_PASSCODE'
})

Generated URLs

start()
// => 'surge:///start'

start({ autoclose: true })
// => 'surge:///start?autoclose=true'

stop()
// => 'surge:///stop'

toggle({ autoclose: true })
// => 'surge:///toggle?autoclose=true'

installConfig({
  url: 'https://example.com/surge.conf',
})
// => 'surge:///install-config?url=https%3A%2F%2Fexample.com%2Fsurge.conf'

xCallbackStart()
// => 'surge://x-callback-url/start'

xCallbackStop()
// => 'surge://x-callback-url/stop'

xCallbackToggle()
// => 'surge://x-callback-url/toggle'

Official Documentation

• Surge URL Scheme

Official Documentation

• URL scheme