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, default7890): 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
| Process | What it does | Source |
|---|---|---|
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 app | Desktop 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
| Platform | Local port | Enhanced Mode | Notes |
|---|---|---|---|
| Windows 10 or later | yes | TUN (Wintun) | Core runs as a Windows service, so Enhanced Mode needs no elevated app |
| macOS | yes | TUN (utun) | Core needs root for TUN |
| Linux | yes | eBPF (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
| Page | What it covers |
|---|---|
| Quick Start | A first profile that loads on every platform, validating it, activating it, pointing programs at the local port, turning on Enhanced Mode |
| How Specola Works | The life of one connection: ingress, process, DNS, sniffing, rules, groups, dialing, telemetry; what a reload keeps |
| Architecture | Core 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
| Page | What it covers |
|---|---|
| General | [general]: route mode, local port and protocols, LAN access, logging, api-listen |
| Proxies | [[proxy]]: every proxy type and its fields |
| TLS | The tls table of a proxy: server name, ALPN, certificates, Reality |
| Transport | The transport table of VMess and VLESS: raw, WebSocket, HTTP, HTTPUpgrade, gRPC |
| Proxy Groups | [[proxy-group]]: select, url-test, fallback, load-balance, health checks |
| Proxy Chains | dialer-proxy: reaching one proxy through another |
| Rules | [route]: rule types, first-match order, rule sets, GeoIP and GeoSite, bypass, per-ingress FINAL |
| Process Rules | Routing 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 |
| Modules | Files merged on top of a profile, for changes you share between profiles |
| Providers | What replaces proxy providers and rule providers |
| Subscriptions | The state of profiles downloaded from a URL, and what to do today |
| Full Configuration | Every field in one place |
Enhanced Mode
| Page | What it covers |
|---|---|
| Enhanced Mode | [enhanced-mode]: what it does, backends, choosing per platform |
| TUN | Windows and macOS: routes, excluded routes, DNS redirection |
| Linux eBPF | Linux: requirements, what is captured, unmatched traffic, troubleshooting |
Reference
| Page | What it covers |
|---|---|
| CLI | Core command-line options and validating a profile |
| Control API | The MessagePack RPC methods the app and scripts use |
| Tools | Latency 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.
