Quick Start
This page takes you from nothing to a working profile:
- Write a small profile: a local port, one proxy, a few rules and
FINAL. - Validate it.
- Activate it in the Specola app.
- Point a browser, a tool or the whole system at the local port.
- Optionally, turn on Enhanced Mode so programs that ignore proxy settings are routed too.
The profile below needs no extra files and loads unchanged on Windows, macOS and Linux.
A first profile
[general]
route-mode = "rule"
port = 7890
protocols = "mixed"
[[proxy]]
name = "work"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "me"
password = "change-me"
[route]
rules = [
# Private networks stay direct
"IP-CIDR,10.0.0.0/8,DIRECT",
"IP-CIDR,172.16.0.0/12,DIRECT",
"IP-CIDR,192.168.0.0/16,DIRECT",
# These sites go through the proxy
"DOMAIN-SUFFIX,github.com,work",
"DOMAIN-SUFFIX,githubusercontent.com,work",
# These programs go through the proxy, on every platform (Windows adds .exe)
"PROCESS-NAME-REGEX,^(git|git-remote-https?|curl|cargo|node)(\\.exe)?$,work",
# Everything else goes direct
"FINAL,DIRECT",
]Replace the server, port and credentials with a SOCKS5 server you run or are allowed to use. For other proxy types (Shadowsocks, VMess, VLESS, Trojan, Hysteria2 and more), see Proxies.
What each part does:
| Part | Meaning |
|---|---|
route-mode = "rule" | Decide each connection by the rules. global sends everything to global-proxy, direct sends everything direct. |
port = 7890, protocols = "mixed" | One local port on 127.0.0.1:7890 that accepts both HTTP and SOCKS5. |
[[proxy]] | One upstream server, named work. Rules refer to it by that name, with the same capitalisation. |
rules | Checked from top to bottom. The first rule that matches decides. The list must end with FINAL. |
The process rule matches the program by its file name. The pattern ends in (\.exe)? because Windows reports git.exe where macOS and Linux report git, and Git for Windows opens HTTPS connections from git-remote-https.exe. Read Process Rules before you write your own; a name that your platform does not report never matches, without any warning.
Every [[proxy]] needs name, type, server and port. Nested settings of a proxy, such as tls, must be written as inline tables (tls = { server-name = "proxy.example.org" }).
Where profiles live
Save the file with a .toml extension in the Profiles folder. The app lists every .toml file in this folder, and Core finds a profile here by its file name.
| Platform | Profiles folder |
|---|---|
| Windows | %LOCALAPPDATA%\Specola\profiles\ |
| macOS | ~/Library/Application Support/com.specola.Specola/profiles/ |
| Linux | $XDG_CONFIG_HOME/specola/profiles/, normally ~/.config/specola/profiles/ |
You can also keep the file elsewhere and use Import file in the app, which copies it into the Profiles folder. An import never overwrites a profile of the same name.
Next to a profile, Specola may keep two small files: <name>.toml.modules (the modules the profile applies) and <name>.toml.disabled-rules (rules you switched off in the app). Leave them next to the profile when you copy or rename it by hand.
Validate the profile
Core can check a profile without starting anything. It needs no administrator rights.
# Windows (in the Specola installation folder)
specola-service.exe --test-config --config my.toml
# macOS and Linux
specola-core --test-config --config my.toml-t is the short form of --test-config. A relative path is looked up in the Profiles folder first, then next to the Core executable, not in the current directory. Use an absolute path for a file somewhere else.
The result is either Config validation passed: <path> or Config validation failed: followed by the problem. Validation also checks the files the profile refers to (GeoIP data, rule-set files) and downloads remote ones, so a profile that passes here also loads in the app.
Common errors:
| Message | Fix |
|---|---|
Unknown general field 'mixed-port' | write port |
Use general.port and general.api-listen | port/protocols and api-listen belong in [general] |
inbound.type contains unsupported value '...' | protocols accepts mixed, socks5 (socks), http, none, or an array of them |
Unsupported top-level field '...' | only general, proxy, proxy-group, route, dns, sniffer and enhanced-mode are allowed at the top level |
Rule list requires an explicit FINAL target | end [route].rules with "FINAL,<target>" |
FINAL must be the last rule | move FINAL to the end |
Rule references unknown outbound: X | X must be DIRECT, REJECT, a proxy or a group, with the same capitalisation |
Global mode requires an existing proxy target | set global-proxy to an existing proxy or group |
GEOIP rule requires a geoip resource | set [route] geoip, see Rules |
enhanced-mode.backend=tun is not supported on Linux; use ebpf or disable enhanced mode | remove backend or write ebpf on Linux |
Unknown enhanced-mode field: type | the key is backend |
Warnings such as Ignoring configuration field 'metadata' in the minimal build are not errors: Core drops that section and loads the rest.
Activate the profile in the app
First launch on macOS
Specola for macOS is not notarized by Apple, so the first time you open it macOS says it cannot verify the developer. Open System Settings → Privacy & Security, scroll down and choose Open Anyway next to the message about Specola, then confirm. You only do this once per version. Instead, you can clear the download flag in Terminal:
xattr -dr com.apple.quarantine /Applications/specola-qml.appAfter an update, macOS may ask again for permissions you granted before, such as Local Network.
- Open Specola and go to Profiles.
- If the profile is not listed, use Import file or drop the
.tomlfile on the page. - Select it and choose Use this profile.
Core loads the profile. If it is invalid, the app shows Core's reason and the profile that was running before keeps running. When you later edit the file by hand, activate it again: Core applies the changes in place without a restart (see what a reload keeps).
Without the app, start Core with the profile directly:
specola-core --config my.toml # macOS, Linux
specola-service.exe --config my.toml # Windows, from a terminalStop it with Ctrl+C. Only one Core runs per computer; a second one exits with Another specola-core process is already running. On Windows, that includes the installed specola-service service.
Send traffic to the local port
Core only listens on 127.0.0.1:7890. It never changes the operating system's proxy settings. The System proxy switch in the app starts and stops this local port; it does not configure Windows, macOS or Linux to use it. Point programs at the port yourself.
One command or tool
curl -x http://127.0.0.1:7890 -I https://github.com
curl -x socks5h://127.0.0.1:7890 -I https://github.comMany command-line tools read proxy variables:
# macOS, Linux
export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890 all_proxy=socks5h://127.0.0.1:7890# Windows PowerShell, current window only
$env:HTTP_PROXY = "http://127.0.0.1:7890"; $env:HTTPS_PROXY = "http://127.0.0.1:7890"Git has its own setting: git config --global http.proxy http://127.0.0.1:7890.
The whole system
Set an HTTP proxy of 127.0.0.1, port 7890, in the system settings. Most browsers and many applications follow it.
| Platform | Where |
|---|---|
| Windows 11 | Settings > Network & internet > Proxy > Manual proxy setup: turn on Use a proxy server, address 127.0.0.1, port 7890 |
| macOS | System Settings > Network > your network > Details > Proxies: Web proxy (HTTP) and Secure web proxy (HTTPS), 127.0.0.1 port 7890 |
| Linux (GNOME) | Settings > Network > Network Proxy > Manual: HTTP and HTTPS proxy 127.0.0.1 port 7890 |
Firefox can use its own proxy settings instead of the system's (Settings > Network Settings).
Turn the system proxy off again when Core is not running, or programs that follow it cannot connect.
Check that it works
Open Connections in the app. Each connection shows the rule that matched, the proxy it used and, for programs on this computer, the process name. A connection to github.com should show DOMAIN-SUFFIX and work; most other sites FINAL and DIRECT.
If nothing appears, the program is not using the port. If a connection to the proxy fails, test the proxy alone: set route-mode = "global" and global-proxy = "work", activate, and try again.
Turn on Enhanced Mode
The local port only sees programs that use it. Enhanced Mode captures the traffic of programs that ignore proxy settings, and lets process rules see every program. Add this to the profile:
[enhanced-mode]
enable = trueLeave backend out: Core uses tun on Windows and macOS and ebpf on Linux, so the same file works everywhere. Enhanced Mode needs administrator rights, and it changes routes and DNS on the system while it runs. Keep port above 0; Linux eBPF hands captured connections to the local port.
| Platform | How to run it |
|---|---|
| Windows | The installed app runs Core as the specola-service service, which has the rights TUN needs. Activate the profile, or use the Enhanced mode switch in the tray or on Overview. If Core was started some other way without administrator rights, the app shows Administrator rights required. From a terminal, run Core in an Administrator terminal. |
| macOS | TUN needs root. A Core started by the app is not root, and turning Enhanced Mode on then fails with TUN requires administrator privileges. Start Core with the profile instead, sudo specola-core --config my.toml; the app connects to the running Core. Started without sudo, a release build asks for an administrator password when its startup profile needs TUN. |
| Linux | eBPF needs root and Linux 5.17 or newer with cgroup v2 and BTF. Start Core with the profile: sudo specola-core --config my.toml. Started without sudo, a release build asks for authorisation (polkit) when its startup profile needs eBPF. |
Under sudo, a relative --config path is still looked up in your own Profiles folder, and Core keeps using your own data folders.
The switches in the app change the running Core only; the profile file keeps its own [enhanced-mode] enable, and activating the profile again applies the file's value.
Read Enhanced Mode, then TUN or Linux eBPF, before relying on it. On Linux in particular, eBPF decides in the kernel which connections reach Core, and destinations on private networks are never captured.
Next steps
Add a group
A group picks one of its members. url-test uses the fastest member, fallback the first one that works:
[[proxy]]
name = "work-2"
type = "socks5"
server = "proxy2.example.org"
port = 1080
[[proxy-group]]
name = "auto"
type = "url-test"
proxies = ["work", "work-2"]
url = "https://www.gstatic.com/generate_204"
interval = 300Without interval the group never tests its members. Point domain rules at the group: "DOMAIN-SUFFIX,github.com,auto". See Proxy Groups.
For process rules, prefer a proxy over a group if you rely on failover. On Linux with eBPF, a process rule that targets a group picks one member the first time it matches and keeps it until the profile is reloaded: url-test does not switch and fallback does not fail over for that rule. See pinned members.
Learn more
- How Specola Works: what happens to one connection, step by step.
- Rules: every rule type, rule sets, GeoIP and GeoSite.
- DNS: how Enhanced Mode answers DNS.
- Modules: keep shared changes in one file applied to several profiles.
