Skip to content

Specola Manual ​

Specola routes the network connections of your computer by rules. You describe proxies, groups and rules in one TOML file, the profile. Specola then sends each connection to DIRECT, REJECT, a proxy or a proxy group, depending on its destination, the program that opened it, or where it came from.

Connections reach Specola in two ways:

  • The local port ([general] port, default 7890): an HTTP and SOCKS5 proxy on your computer. Programs use it when you point them, or the system proxy setting, at it.
  • Enhanced Mode: Specola captures traffic without any proxy setting. Windows and macOS use a TUN adapter, Linux uses eBPF.

Specola does not include proxy servers. You add servers you run yourself or are allowed to use.

Two processes ​

ProcessWhat it doesSource
Core (specola-service.exe on Windows, specola-core on macOS and Linux)Loads the profile, runs the local port, Enhanced Mode, DNS, rules, proxy protocols and health checks. Runs without the app.src/
Specola appDesktop UI built with Qt Quick (QML). Starts or connects to Core, edits profiles, shows connections and logs.gui/qml/

The app never reaches into Core directly. It sends requests over the control API: MessagePack RPC over a local named pipe (Windows) or Unix socket (macOS, Linux), and optionally over TCP when the profile sets api-listen. Scripts can use the same API. See Architecture and Control API.

On Windows the installed app runs Core as the specola-service Windows service. On macOS and Linux the app starts Core as its own child process.

Platforms ​

PlatformLocal portEnhanced ModeNotes
Windows 10 or lateryesTUN (Wintun)Core runs as a Windows service, so Enhanced Mode needs no elevated app
macOSyesTUN (utun)Core needs root for TUN
LinuxyeseBPF (kernel 5.17+, cgroup v2, BTF)Core needs root for eBPF; Linux builds can also run as a router gateway

Core builds for all three. Check the download page for the installers that are published for your platform.

How this manual is organised ​

Start here ​

PageWhat it covers
Quick StartA first profile that loads on every platform, validating it, activating it, pointing programs at the local port, turning on Enhanced Mode
How Specola WorksThe life of one connection: ingress, process, DNS, sniffing, rules, groups, dialing, telemetry; what a reload keeps
ArchitectureCore and app processes, the control API, the parts inside Core, the Windows service, data folders, how a profile becomes the running configuration

Writing a profile ​

PageWhat it covers
General[general]: route mode, local port and protocols, LAN access, logging, api-listen
Proxies[[proxy]]: every proxy type and its fields
TLSThe tls table of a proxy: server name, ALPN, certificates, Reality
TransportThe transport table of VMess and VLESS: raw, WebSocket, HTTP, HTTPUpgrade, gRPC
Proxy Groups[[proxy-group]]: select, url-test, fallback, load-balance, health checks
Proxy Chainsdialer-proxy: reaching one proxy through another
Rules[route]: rule types, first-match order, rule sets, GeoIP and GeoSite, bypass, per-ingress FINAL
Process RulesRouting by program: names and paths per platform, include-children, Linux eBPF specifics
DNS[dns]: Fake-IP and real-IP modes, upstreams, hosts, the DNS listener
Sniffer[sniffer]: reading the host name from HTTP and TLS on captured connections
ModulesFiles merged on top of a profile, for changes you share between profiles
ProvidersWhat replaces proxy providers and rule providers
SubscriptionsThe state of profiles downloaded from a URL, and what to do today
Full ConfigurationEvery field in one place

Enhanced Mode ​

PageWhat it covers
Enhanced Mode[enhanced-mode]: what it does, backends, choosing per platform
TUNWindows and macOS: routes, excluded routes, DNS redirection
Linux eBPFLinux: requirements, what is captured, unmatched traffic, troubleshooting

Reference ​

PageWhat it covers
CLICore command-line options and validating a profile
Control APIThe MessagePack RPC methods the app and scripts use
ToolsLatency and other diagnostic tests offered through the control API

Before you start ​

  • Profiles are TOML files. Unknown keys are errors in most sections, so a typo stops the profile from loading instead of being ignored. Validate a profile before you activate it (see Quick Start).
  • The local port and Enhanced Mode are separate. The local port only sees programs that use it. Enhanced Mode sees programs that ignore proxy settings, and it changes routes or DNS on the system.
  • App settings are not profile settings. Theme, window and tray options live in the app. The profile only holds what Core runs.
  • Change one layer at a time. Get the local port working with FINAL,DIRECT, then add one proxy, then rules, and turn on Enhanced Mode last. When something breaks, the log names the first error.