Specola Manual
Specola is a rule-based traffic router for developers. It reads a plain TOML profile, accepts traffic from a local HTTP/SOCKS5 listener or — on Linux — from transparent eBPF capture, and sends each connection to DIRECT, REJECT, a proxy, or a proxy group.
Specola is two processes:
specola-core— written in C++20 on Asio coroutines. It owns configuration, listeners, routing, DNS, proxy protocols, and Enhanced Mode, and runs fine without any UI.- Desktop UI — built with Qt Quick (QML). It starts and monitors Core and talks to it only through the MessagePack RPC control API over local IPC.
Core topics
These pages cover what most setups need, in the order you should configure them:
| Step | Page | What it covers |
|---|---|---|
| 1 | General | Profile metadata, Mixed HTTP/SOCKS5 port, Direct / Global / Rule modes, logging, control API |
| 2 | Proxies | Upstream servers you operate or are authorized to use |
| 3 | Proxy Groups | select, url-test, fallback, load-balance and health checks |
| 4 | Rules | First-match rules on domain, IP, GeoIP, port and process |
| 5 | DNS | Upstreams, policy, fallback, hosts, Fake-IP |
| 6 | Linux eBPF | Process-aware transparent capture through cgroup v2 |
For every supported field, see Full Configuration.
First use
- Follow Quick Start and prove the Mixed listener works in Direct mode.
- Add one proxy from Proxies, switch to Global, and verify the remote path.
- Add Rules and proxy groups only after the proxy works by itself.
- On Linux, enable eBPF Enhanced Mode last, with a known rollback path.
Three concepts to confirm first
Mixed listener and Enhanced Mode are different entry paths. The Mixed listener serves applications explicitly configured for 127.0.0.1:<inbound.port>. Enhanced Mode captures traffic from applications that ignore proxy settings and changes system network state.
A configuration is not a proxy service. The built-in Direct profile proves the local application works; Specola does not provide remote servers.
UI settings and Core TOML are separate. Window, tray, theme, and refresh preferences are not Core configuration fields.
Troubleshooting order
Check one layer at a time: UI/Core connection → Mixed listener → Direct → Global → Rule → Enhanced. Keep the first error in Logs, and avoid changing DNS, routing, and transparent capture together.