Architecture
Specola is two programs. Core does all the networking. The Specola app is a desktop UI that controls Core. They only talk through the control API, so Core also runs on its own, under another UI, or driven by scripts.
Specola app (Qt Quick) scripts, remote app
│ │
│ local IPC │ TCP (api-listen, optional)
▼ ▼
┌──────────────────── Core ────────────────────┐
│ control API → CoreRuntime │
│ proxies · routing · local port · DNS │
│ Enhanced Mode · health checks · tools │
│ telemetry · logging · license │
└──────────────────────────────────────────────┘Core and the app
| Core | Specola app | |
|---|---|---|
| Executable | specola-service.exe (Windows), specola-core (macOS, Linux) | the Specola desktop app |
| Source | src/ (C++20, Asio) | gui/qml/ (Qt Quick) |
| Owns | the profile, listeners, DNS, rules, proxy protocols, Enhanced Mode | windows, tray, theme, page state |
| Needs administrator rights | only for Enhanced Mode | never |
Who starts Core:
| Platform | Started by | Lifetime |
|---|---|---|
| Windows (installed) | the Service Control Manager, as the specola-service service (LocalSystem) | independent of the app; the app asks it to start and stop |
| macOS, Linux | the app, as a child process with --parent-pid | exits when the app exits |
| any | you, from a terminal (--config <file>) | until Ctrl+C; the app connects to it |
When the app starts, it first tries to connect to a running Core and only starts one if none answers. Only one Core runs per computer; a second one exits at once with Another specola-core process is already running.
Core started without --config waits for the app to activate a profile. If a profile fails to start, Core keeps the control API open so another profile can be chosen.
The control API
The app and Core speak MessagePack RPC. Requests, replies and streams are defined in api/*.toml (for example profile.activateProfile, proxy.selectGroupMember, routing.setMode). See Control API.
| Transport | Address | Who can connect |
|---|---|---|
| Local IPC (always on) | Windows: named pipe \\.\pipe\specola; macOS, Linux: Unix socket /tmp/specola.sock | Windows: local users; macOS, Linux: the user who started Core (socket mode 0600, owned by the invoking user when Core runs as root) |
| TCP (optional) | [general] api-listen, for example "127.0.0.1:9090" | only clients from loopback and private networks: 10/8, 172.16/12, 192.168/16, 100.64/10, 169.254/16, fc00::/7, fe80::/10 |
--ipc-endpoint <path>moves the local endpoint.- The TCP API has no authentication. Bind it to loopback unless you trust every device on the network. License operations and
core.shutdownare refused over TCP. api-listenfollows the profile: activating a profile opens, moves or closes it without a restart.- Before a profile is loaded, only the
sys.*,core.*,profile.*,license.*,overview.*,ssh.*andgateway.*methods are served; others replyCore initialization is not complete. While a profile loads, requests replyCore is loading a Profile.
The app also tells Core where the user's Profiles folder is (profile.setDirectory). Core then reads and writes profile files with that user's rights, even when Core itself runs as root or LocalSystem. When you edit proxies or rules in the app, Core writes the change into the profile file and reloads it; a change that does not load is not saved.
Inside Core
Core holds one immutable configuration snapshot and a set of parts built from it (CoreRuntime, src/core/core_runtime.hpp):
| Part | Job |
|---|---|
| Logging | log level, in-memory log, daily log files |
| License | license state (license.json in the data folder) |
| Telemetry | connections, per-rule, per-proxy and total traffic counters |
| Proxies | one instance per [[proxy]] and [[proxy-group]], group selection |
| Routing | the rule table, route mode, bypass, final targets, Fake-IP and DNS mappings |
| Inbound | the local HTTP/SOCKS5 port |
| DNS | answers captured queries, Fake-IP pool, optional DNS listener |
| Enhanced Mode | TUN on Windows and macOS, eBPF on Linux |
| Health checks | periodic URL tests of group members |
| Tools | latency and other tests offered through the control API, see Tools |
Core starts them in this order: license, proxies and groups, rules, DNS, local port, health checks, then Enhanced Mode last, once everything it redirects traffic into is ready. On Linux, the router gateway (--gateway <file>) runs next to these parts and can use the DNS module for LAN clients.
Windows service mode
The Windows installer registers Core as the specola-service service. It runs as LocalSystem, so Enhanced Mode works while the app runs with normal rights.
- Its own data lives in
%ProgramData%\Specola, readable and writable only by SYSTEM and Administrators. - It has no Profiles folder of its own. The app binds the signed-in user's
%LOCALAPPDATA%\Specola\profiles, and the service reads it as that user. - The named pipe lets interactive users connect, so the unelevated app can control it.
- A killed Core can leave the Windows DNS redirect (an NRPT rule) behind. Core removes it on every start, and
specola-service.exe --reset-network, run as Administrator, removes it by hand.
Data folders
| Folder | Windows | macOS | Linux |
|---|---|---|---|
Data (resources, license.json) | %LOCALAPPDATA%\Specola | ~/Library/Application Support/com.specola.Specola | $XDG_CONFIG_HOME/specola (~/.config/specola) |
| Profiles | <data>\profiles | <data>/profiles | <data>/profiles |
| Download cache | <data>\Cache\remote | ~/Library/Caches/com.specola.Specola/remote | $XDG_CACHE_HOME/specola/remote |
| Logs | <data>\Logs | ~/Library/Logs/com.specola.Specola | $XDG_STATE_HOME/specola/log |
| Runtime | <data>\Runtime | ~/Library/Caches/com.specola.Specola/runtime | $XDG_RUNTIME_DIR/specola |
- The Windows service uses
%ProgramData%\Specolaas its data folder. SPECOLA_LOG_DIRmoves the logs. There is no option to move the other folders.- A Core started with
sudoor polkit uses the folders of the user who started it.
Inside the Profiles folder:
profiles/
├── work.toml a profile
├── work.toml.modules modules it applies, one per line (optional)
├── work.toml.disabled-rules rules switched off in the app (optional)
├── modules/home-lan.toml a module, see Modules
└── .removed/ removed profiles, kept hereFrom profile file to running configuration
When a profile is activated (or given with --config), Core:
- Reads the file, then merges the modules listed in
<profile>.modules. - Drops ignored sections such as
[metadata], with a warning, and rejects unknown keys. - Parses the result into its configuration (
AppConfig) and checks it: names, references, rule syntax,FINALat the end, platform limits. - Finds the files the profile refers to (relative paths: profile folder, then data folder, then
resources/next to the executable) and downloads remote GeoIP, GeoSite and rule-set files, falling back to the cached copy. - Applies
<profile>.disabled-rules.
--test-config runs exactly these steps and stops. Any error ends the load and the running profile stays untouched.
Then:
- First profile: Core builds every part and starts it (
CoreRuntime::bootstrap). - Later profiles: Core compares the new configuration with the running one (
ConfigDiff) and applies only the differences in place: listener, control API, proxy and rule tables, DNS, Enhanced Mode, log settings, route mode. What cannot be applied in place (and, under Linux eBPF, any change to the listener, DNS, Enhanced Mode or sniffer) rebuilds all parts from the new configuration. If that fails, Core rebuilds the previous configuration; if even that fails, Core stops and must be restarted.
How Specola Works lists what a reload keeps.
See also
- CLI for Core's command-line options.
- Control API for the methods.
- Quick Start for a first profile.
