Skip to content

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.

text
 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 ​

CoreSpecola app
Executablespecola-service.exe (Windows), specola-core (macOS, Linux)the Specola desktop app
Sourcesrc/ (C++20, Asio)gui/qml/ (Qt Quick)
Ownsthe profile, listeners, DNS, rules, proxy protocols, Enhanced Modewindows, tray, theme, page state
Needs administrator rightsonly for Enhanced Modenever

Who starts Core:

PlatformStarted byLifetime
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, Linuxthe app, as a child process with --parent-pidexits when the app exits
anyyou, 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.

TransportAddressWho can connect
Local IPC (always on)Windows: named pipe \\.\pipe\specola; macOS, Linux: Unix socket /tmp/specola.sockWindows: 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.shutdown are refused over TCP.
  • api-listen follows 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.* and gateway.* methods are served; others reply Core initialization is not complete. While a profile loads, requests reply Core 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):

PartJob
Logginglog level, in-memory log, daily log files
Licenselicense state (license.json in the data folder)
Telemetryconnections, per-rule, per-proxy and total traffic counters
Proxiesone instance per [[proxy]] and [[proxy-group]], group selection
Routingthe rule table, route mode, bypass, final targets, Fake-IP and DNS mappings
Inboundthe local HTTP/SOCKS5 port
DNSanswers captured queries, Fake-IP pool, optional DNS listener
Enhanced ModeTUN on Windows and macOS, eBPF on Linux
Health checksperiodic URL tests of group members
Toolslatency 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 ​

FolderWindowsmacOSLinux
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%\Specola as its data folder.
  • SPECOLA_LOG_DIR moves the logs. There is no option to move the other folders.
  • A Core started with sudo or polkit uses the folders of the user who started it.

Inside the Profiles folder:

text
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 here

From profile file to running configuration ​

When a profile is activated (or given with --config), Core:

  1. Reads the file, then merges the modules listed in <profile>.modules.
  2. Drops ignored sections such as [metadata], with a warning, and rejects unknown keys.
  3. Parses the result into its configuration (AppConfig) and checks it: names, references, rule syntax, FINAL at the end, platform limits.
  4. 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.
  5. 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 ​