Skip to content

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] hosts and listener, and [route] geoip and geosite.
  • Names are case-sensitive. DIRECT and REJECT are 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:

bash
specola-core --test-config --config home.toml       # Windows: specola-service.exe

Annotated profile ​

The servers, passwords and UUIDs are placeholders; replace them with servers you are allowed to use.

toml
# ── 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 | core

Field index ​

SectionKeysPage
[general]route-mode, global-proxy, log-level, log-file, port, protocols, allow-lan, api-listen, ipv6General
[general.inbound]port, protocols (older place for the same keys)General
[[proxy]]name, type, server, port, type-specific keysProxies
[[proxy]] tlsenabled, server-name, alpn, skip-cert-verify, certificate, certificate-path, realityTLS
[[proxy]] transporttype (raw, ws, http, httpupgrade, grpc) and its keys; VMess and VLESS onlyTransport
[[proxy]] dialer-proxya proxy or group to dial throughProxy Chains
[[proxy-group]]name, type, proxies, url, interval, tolerance, strategy, dialer-proxy, iconProxy Groups
[route]rules, rule-set, geoip, geosite, asn, geo-update, bypass, final-mixed, final-enhanced, resolve-unknown-domainsRules
[route] PROCESS-* rulesPROCESS-NAME, PROCESS-PATH and their wildcard and regex forms, include-childrenProcess Rules
[dns]ipv6, mode, fake-ip-range, nameserver-proxy, hosts, listenerDNS
[sniffer]enable, protocols, override-destination, http-ports, tls-ports, timeout-ms, max-bytesSniffer
[enhanced-mode]enable, backend, ip-versionEnhanced Mode
[enhanced-mode.tun]auto-route, address, routes, exclude-routes, dns-hijack, dns-namespacesTUN
[enhanced-mode.ebpf]unmatched-trafficLinux eBPF

Ignored and rejected ​

These names from older profiles load with a warning (Ignoring configuration field ...) and have no effect. Their content is dropped:

IgnoredNote
[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-providersuse 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-probenot available (Tools)
[[proxy-groups]] (plural)the groups in it are lost; write [[proxy-group]]
enhanced-mode.process-proxyprocess routing is written as process rules
general.api-secretdropped without a warning

These are errors:

RejectedWrite 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-controllerport, api-listen
protocols value httpshttp
dialer_proxydialer-proxy
proxy types ssh, mieru, sudoku—
[dns] keys other than the six above ([dns.upstream], nameserver-policy, ...) and tls:// nameserverssee DNS
the group key uselist members in proxies
rule type SUB-RULE—
enhanced-mode.typebackend
enhanced-mode.ebpf.process-routingnothing: Core derives it from the rules
backend = "tun" with enable = true on Linuxebpf

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-set entries are merged by name; an entry with an existing name replaces it.
  • A module's route.rules go 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.