Full Configuration

A Specola profile is one TOML file. Only [general] is needed; every other section is optional. This page shows a complete profile with every section, then lists all supported fields.

If you are starting out, follow Quick Start instead and come back here as a reference.

Annotated profile

# ── General ─────────────────────────────────────────────────────────────
[general]
route-mode = "rule"            # direct | global | rule
global-proxy = "work"          # used when route-mode = "global"
log-level = "info"             # trace | debug | info | warn | error | critical | off
port = 7890                    # local HTTP/SOCKS5 port; 0 disables it
protocols = "mixed"            # mixed | http | socks5 | none, or a list
allow-lan = false              # true listens on 0.0.0.0
api-listen = ""                # optional TCP control API, e.g. "127.0.0.1:9090"
api-secret = ""

# ── Proxies: servers you operate or are authorized to use ──────────────
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.com"
port = 8443
username = "me"
password = "change-me"

[proxy.tls]
server-name = "proxy.example.com"

[[proxy]]
name = "home"
type = "ss"
server = "home.example.com"
port = 8388
cipher = "2022-blake3-aes-128-gcm"
password = "base64-key-from-your-server"

# ── Proxy groups: members are proxies, DIRECT or REJECT (no nesting) ───
[[proxy-group]]
name = "work"
type = "fallback"              # select | url-test | fallback | load-balance
proxies = ["office", "home", "DIRECT"]
url = "https://www.gstatic.com/generate_204"
interval = 300                 # seconds; without it no health check runs

# ── Rules: first match wins, FINAL last ────────────────────────────────
[rule]
list = [
  "PROCESS-NAME,git-remote-http,work",
  "PROCESS-NAME,cargo,work",
  "DOMAIN-SUFFIX,corp.example.com,office",
  "DOMAIN,registry.npmjs.org,work",
  "RULE-SET,blocked,REJECT",
  "IP-CIDR,10.0.0.0/8,DIRECT,no-resolve",
  "IP-CIDR,192.168.0.0/16,DIRECT,no-resolve",
  "FINAL,DIRECT",
]

# Data files for GEOIP / GEOSITE / IP-ASN rules (absolute paths).
# [rule.cache]
# geoip = "/home/me/.local/share/specola/geoip.dat"
# geosite = "/home/me/.local/share/specola/geosite.dat"

# A reusable list used by RULE-SET,blocked,... above.
[[rule.cache.rule-set]]
name = "blocked"
behavior = "domain"            # classical | domain | ipcidr
path = "/home/me/.config/specola/blocked-domains.txt"

# ── DNS: all optional ──────────────────────────────────────────────────
[dns]
ipv6 = false

[dns.upstream]
default = ["https://1.1.1.1/dns-query"]
# direct = []                  # empty: system resolvers

[dns.nameserver-policy]
"+.corp.example.com" = "udp://10.0.0.53"

[dns.tun]
mode = "fake-ip"
fake-ip-filter = ["+.lan", "+.local"]

# ── Sniffer: on by default ─────────────────────────────────────────────
[sniffer]
enable = true

# ── Enhanced Mode: ebpf on Linux, tun on macOS and Windows ─────────────
[enhanced-mode]
enable = false
type = "ebpf"
ip-version = "ipv4"

[enhanced-mode.ebpf]
process-routing = true

The rule set file blocked-domains.txt must exist when Core starts; specola-core -t only checks that a path is set.

Field index

Section	Fields	Page
[general]	route-mode, global-proxy, log-level, port, protocols, allow-lan, ipv6, api-listen, api-secret	General
[[proxy]]	name, type, server, port, dialer-proxy, type-specific fields, [proxy.tls], [proxy.transport]	Proxies
[[proxy-provider]]	name, url, path, proxy	Providers
[[proxy-group]]	name, type, proxies, url, interval, tolerance, strategy, dialer-proxy, icon	Proxy Groups
[rule]	list, resolve-unknown-domains	Rules
[rule.cache]	geoip, geosite, asn, [[rule.cache.rule-set]]	Rules
[dns]	ipv6, respect-rules, cache fields, use-hosts, use-system-hosts	DNS
[dns.upstream]	default, direct, bootstrap, proxy-server, fallback, direct-follow-policy	DNS
[dns.tun]	mode, Fake-IP fields, route-resolution, probe-resolver, probe-timeout-ms	DNS
[dns.system-proxy]	route-resolution, probe-resolver, probe-timeout-ms	DNS
[dns.listener]	enable, address	DNS
[dns.nameserver-policy], [dns.fallback-filter]		DNS
[sniffer]	enable, protocols, http-ports, tls-ports, override-destination, timeout-ms, max-bytes	Sniffer
[enhanced-mode]	enable, type, ip-version	Enhanced Mode
[enhanced-mode.ebpf]	process-routing	Linux eBPF
[enhanced-mode.tun]	stack, auto-route, auto-detect-interface, routes, extra-routes, dns-hijack	TUN

Not available in the current build

These sections from older profiles are ignored with a warning, so old files still load, but they have no effect: [metadata], [[rule-set]] (use [[rule.cache.rule-set]]), [[module]], [[subscription]], [hosts], [gateway], [tunnel], [ntp].

These are rejected: top-level [inbound], mixed-port, external-controller, tun-rules, protocols value https, proxy types ssh, mieru, sudoku, [dns.hosts] enable = true, the group field use, and enhanced-mode.type = "tun" on Linux.