Full Configuration
A Specola profile is one TOML file. Every section and every key is optional; what you leave out takes its default. This page shows a profile that uses every section, then indexes all keys.
Starting out? Follow Quick Start and come back here as a reference.
The exhaustive version, with every key, every proxy type and comments on each value, ships as resources/client/reference.toml. It loads as written on Windows, macOS and Linux.
Rules for the file
- Top-level sections:
[general],[[proxy]],[[proxy-group]],[route],[dns],[sniffer],[enhanced-mode]. Anything else is an error, except the ignored names below. - Unknown keys are errors everywhere except inside
[[proxy]](and its inline tables) and[sniffer]. A typo is reported, not silently ignored, in every other section. - Tables inside a
[[proxy]](tls,transport,reality,headers) must be inline tables:tls = { server-name = "..." }. So must[dns]hostsandlistener, and[route]geoipandgeosite. - Names are case-sensitive.
DIRECTandREJECTare built in; do not declare them. - Windows paths in rules need single-quoted TOML strings:
'PROCESS-PATH,C:\Tools\app.exe,DIRECT'.
Validate a profile without starting Core:
specola-core --test-config --config home.toml # Windows: specola-service.exeAnnotated profile
The servers, passwords and UUIDs are placeholders; replace them with servers you are allowed to use.
# ── General ──────────────────────────────────────────────────────────────
[general]
route-mode = "rule" # rule | global | direct
global-proxy = "SELECT" # target of global mode: a proxy, group, DIRECT or REJECT
log-level = "info" # trace | debug | info | warn | error | critical | off
log-file = true # daily log files, kept 7 days
port = 7890 # local SOCKS5/HTTP port; 0 turns it off
protocols = "mixed" # mixed | socks5 | http | none, or an array
allow-lan = false # true listens on 0.0.0.0
api-listen = "" # optional TCP control API, e.g. "127.0.0.1:9090"
ipv6 = false # accepted, not used by Core
# ── Proxies ──────────────────────────────────────────────────────────────
[[proxy]]
name = "socks-example"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "example-user"
password = "replace-with-password"
[[proxy]]
name = "https-example"
type = "http"
server = "proxy.example.org"
port = 8443
username = "example-user"
password = "replace-with-password"
tls = { server-name = "proxy.example.org" } # an HTTPS proxy
[[proxy]]
name = "vless-ws"
type = "vless"
server = "proxy.example.org"
port = 443
uuid = "b1479ae4-f64b-4b27-bdab-4fb0f4ecdba9"
tls = { server-name = "proxy.example.org" }
transport = { type = "ws", host = ["proxy.example.org"], path = "/ws" }
dialer-proxy = "socks-example" # reach this server through socks-example
# ── Proxy groups: members are proxies, DIRECT or REJECT, never groups ────
[[proxy-group]]
name = "SELECT"
type = "select"
proxies = ["vless-ws", "https-example", "DIRECT"]
[[proxy-group]]
name = "AUTO"
type = "url-test"
proxies = ["vless-ws", "https-example"]
url = "https://www.gstatic.com/generate_204"
interval = 300 # seconds; without it there are no periodic checks
tolerance = 50 # ms a member must be faster before AUTO switches
# ── Routing: first match wins, FINAL last ────────────────────────────────
[route]
rules = [
"IP-CIDR,192.168.0.0/16,DIRECT",
"IP-CIDR6,fc00::/7,DIRECT",
"RULE-SET,private-domains,DIRECT",
"PROCESS-NAME-REGEX,^(git|ssh)(\\.exe)?$,SELECT",
"DOMAIN-SUFFIX,example.net,AUTO",
"FINAL,DIRECT",
]
bypass = ["localhost", "*.local", "127.0.0.0/8", "::1/128"] # always DIRECT, before any rule
final-mixed = "" # FINAL for the local port; empty uses the FINAL rule
final-enhanced = "" # FINAL for Enhanced Mode traffic
resolve-unknown-domains = false
geo-update = "weekly" # daily | weekly | monthly | never
rule-set = [
{ name = "private-domains", type = "inline", behavior = "classical", rules = ["DOMAIN-SUFFIX,lan", "DOMAIN-SUFFIX,home.arpa"] },
]
# geoip = { type = "local", path = "geoip.dat" } # needed only by GEOIP rules
# geosite = { type = "remote", url = "https://example.org/geosite.dat", proxy = "socks-example" }
# asn = "asn.txt" # needed only by IP-ASN rules
# ── DNS: exactly these six keys ──────────────────────────────────────────
[dns]
ipv6 = false
mode = "fake-ip" # fake-ip | fake-ip-all | real-ip
fake-ip-range = "198.18.0.1/16"
nameserver-proxy = ["https://1.1.1.1/dns-query", "udp://8.8.8.8:53"]
hosts = { "router.lan" = "192.168.1.1", "nas.lan" = ["192.168.1.10", "fd00::10"] }
listener = { enable = false, address = "127.0.0.1:1053" }
# ── Sniffer: Enhanced Mode and gateway traffic only ──────────────────────
[sniffer]
enable = true
protocols = ["http", "tls"]
override-destination = true
http-ports = [80, 8080]
tls-ports = [443, 8443]
timeout-ms = 500
max-bytes = 16384
# ── Enhanced Mode: needs administrator rights ────────────────────────────
[enhanced-mode]
enable = false
ip-version = "ipv4" # ipv4 | ipv6 | dual
# backend left out: tun on Windows and macOS, ebpf on Linux
[enhanced-mode.tun] # Windows and macOS
auto-route = true
address = "198.19.0.1/30" # Windows only
routes = []
exclude-routes = []
dns-hijack = true # Windows only
dns-namespaces = ["."] # Windows only
[enhanced-mode.ebpf] # Linux
unmatched-traffic = "direct" # direct | coreField index
| Section | Keys | Page |
|---|---|---|
[general] | route-mode, global-proxy, log-level, log-file, port, protocols, allow-lan, api-listen, ipv6 | General |
[general.inbound] | port, protocols (older place for the same keys) | General |
[[proxy]] | name, type, server, port, type-specific keys | Proxies |
[[proxy]] tls | enabled, server-name, alpn, skip-cert-verify, certificate, certificate-path, reality | TLS |
[[proxy]] transport | type (raw, ws, http, httpupgrade, grpc) and its keys; VMess and VLESS only | Transport |
[[proxy]] dialer-proxy | a proxy or group to dial through | Proxy Chains |
[[proxy-group]] | name, type, proxies, url, interval, tolerance, strategy, dialer-proxy, icon | Proxy Groups |
[route] | rules, rule-set, geoip, geosite, asn, geo-update, bypass, final-mixed, final-enhanced, resolve-unknown-domains | Rules |
[route] PROCESS-* rules | PROCESS-NAME, PROCESS-PATH and their wildcard and regex forms, include-children | Process Rules |
[dns] | ipv6, mode, fake-ip-range, nameserver-proxy, hosts, listener | DNS |
[sniffer] | enable, protocols, override-destination, http-ports, tls-ports, timeout-ms, max-bytes | Sniffer |
[enhanced-mode] | enable, backend, ip-version | Enhanced Mode |
[enhanced-mode.tun] | auto-route, address, routes, exclude-routes, dns-hijack, dns-namespaces | TUN |
[enhanced-mode.ebpf] | unmatched-traffic | Linux eBPF |
Ignored and rejected
These names from older profiles load with a warning (Ignoring configuration field ...) and have no effect. Their content is dropped:
| Ignored | Note |
|---|---|
[metadata] | Core never reads it, so subscription settings and download-via in it do nothing. The app reads metadata.name from the file to show the profile's name |
[[module]], modules, [[subscription]], subscriptions, sub-rules, rule-providers | use modules and [route].rule-set |
top-level [hosts] | use [dns].hosts |
[tunnel], [ntp], [gateway], [state] | router settings go in the --gateway file |
ssh-port-forward, ssh-port-forwards, port-forwards, ssh-probe | not available (Tools) |
[[proxy-groups]] (plural) | the groups in it are lost; write [[proxy-group]] |
enhanced-mode.process-proxy | process routing is written as process rules |
general.api-secret | dropped without a warning |
These are errors:
| Rejected | Write instead |
|---|---|
top-level [rule] or rules | [route] rules |
top-level [[rule-set]] | [route] rule-set |
top-level [inbound] | port and protocols in [general] |
top-level proxies = [...] | [[proxy]] (proxies is accepted only in module files) |
[[proxy-provider]] and other unknown sections | — |
general.mixed-port, general.external-controller | port, api-listen |
protocols value https | http |
dialer_proxy | dialer-proxy |
proxy types ssh, mieru, sudoku | — |
[dns] keys other than the six above ([dns.upstream], nameserver-policy, ...) and tls:// nameservers | see DNS |
the group key use | list members in proxies |
rule type SUB-RULE | — |
enhanced-mode.type | backend |
enhanced-mode.ebpf.process-routing | nothing: Core derives it from the rules |
backend = "tun" with enable = true on Linux | ebpf |
Sidecar files
Two optional files sit next to a profile. Their names are the profile's file name plus a suffix: for home.toml, home.toml.modules and home.toml.disabled-rules.
<profile>.modules lists the modules the profile applies, one file name per line (work.toml), in order. The files live in the modules folder beside the profile. When the profile loads:
[[proxy]],[[proxy-group]]and[route] rule-setentries are merged by name; an entry with an existing name replaces it.- A module's
route.rulesgo before the profile's own rules; a module listed later goes before an earlier one. - Every other key is merged into the profile, and the module's value wins.
- A module file may write proxies as
proxies = [...]; its[metadata]is ignored. - A missing module file is skipped with a warning; a module that is not valid TOML fails the load.
The app manages this file; see Modules.
<profile>.disabled-rules holds the rules you switched off in the app, one rule text per line. Those rules are skipped when the profile loads; the profile file itself is not changed. A rule is recognised by its exact text, so editing a rule switches it back on. FINAL cannot be switched off.
Both files are read by --test-config too.
Applying changes
Re-activating a profile applies every change in place, without restarting Core: logging, route mode, the local port, api-listen, proxies, groups and rules (group choices and health are kept for what remains), DNS, the sniffer and Enhanced Mode. Under Linux eBPF, changes to the local port, DNS, Enhanced Mode or the sniffer rebuild the whole runtime. A profile that does not load leaves the running one untouched. See General.
