Skip to content
Surge Docs

Run Surge as a system service

Install a system service when Surge should keep running after you close your terminal or start automatically with the machine. The service runs the headless server, not the interactive TUI.

Before you install

Section titled “Before you install”

Start Surge manually first and make sure it can download to the intended location. On Linux and Windows, service management may require sudo or an Administrator terminal.

Install and start

Section titled “Install and start”
Terminal window
surge service install
surge service start
surge service status

The service has its own authentication token. Retrieve it when connecting a remote TUI or configuring the browser extension:

Terminal window
surge service token

Reading the system token may require elevated privileges.

Control the service

Section titled “Control the service”

Use the normal commands once the service is running:

Terminal window
surge add https://example.com/archive.zip
surge ls
surge pause --all

If the local client cannot discover the service token, provide it explicitly with --token or set SURGE_TOKEN.

Stop or remove the service

Section titled “Stop or remove the service”
Terminal window
surge service stop
surge service uninstall

Uninstalling the service does not intentionally delete your completed downloads. Check data locations before manually removing configuration or state files.