Quick Start

This page builds one profile in five steps. Each step is a complete file: copy it, replace the example server details with your own, validate it, and only then move to the next step.

Step	You get
1	A local HTTP/SOCKS5 port that sends everything direct
2	One upstream proxy, used for all traffic
3	A proxy group that falls back when the proxy is down
4	Rules: some traffic through the proxy, the rest direct
5	Linux only: route tools that ignore proxy settings, by process

You can also download the finished files: 01-direct.toml, 02-proxy.toml, 03-group.toml, 04-rules.toml, 05-linux-ebpf.toml.

Where the file goes

Save your profile in the Specola profiles directory, so you can refer to it by file name:

OS	Profiles directory
Linux	~/.config/specola/profiles/
macOS	~/Library/Application Support/com.specola.Specola/profiles/
Windows	%LOCALAPPDATA%\Specola\profiles\

--config also accepts an absolute path to a file anywhere.

Step 1: Direct only

[general]
route-mode = "direct"
log-level = "info"
port = 7890
protocols = "mixed"

That is a complete profile. protocols = "mixed" accepts both HTTP and SOCKS5 on the same port.

Validate it, then start Core:

specola-core -t --config my.toml
specola-core --config my.toml

The first command prints Config validation passed: <path> or the exact field that is wrong. Now point one tool at the local port and check that it still works:

curl -x http://127.0.0.1:7890 https://example.com -I
curl -x socks5h://127.0.0.1:7890 https://example.com -I

If this fails, the problem is local (port in use, firewall, wrong port in the client). Fix it before adding a proxy.

Step 2: Add a proxy

Add one [[proxy]] for a server you operate or are authorized to use, and switch to Global mode so that everything uses it:

[general]
route-mode = "global"
global-proxy = "office"
log-level = "info"
port = 7890
protocols = "mixed"

[[proxy]]
name = "office"
type = "http"
server = "proxy.example.com"
port = 8080
username = "me"
password = "change-me"

Run the same curl commands. If they fail now but worked in step 1, the problem is the proxy itself: address, port, credentials, or TLS. See Proxies for every supported type.

Step 3: Add a proxy group

A group picks one of its members. fallback uses the first member that passes a health check, so traffic keeps working when the proxy is down:

[general]
route-mode = "global"
global-proxy = "work"
log-level = "info"
port = 7890
protocols = "mixed"

[[proxy]]
name = "office"
type = "http"
server = "proxy.example.com"
port = 8080
username = "me"
password = "change-me"

[[proxy-group]]
name = "work"
type = "fallback"
proxies = ["office", "DIRECT"]
url = "https://www.gstatic.com/generate_204"
interval = 300

global-proxy can name a proxy or a group. See Proxy Groups.

Step 4: Add rules

Switch to Rule mode. Rules are checked top to bottom; the first match wins, and the list must end with FINAL:

[general]
route-mode = "rule"
log-level = "info"
port = 7890
protocols = "mixed"

[[proxy]]
name = "office"
type = "http"
server = "proxy.example.com"
port = 8080
username = "me"
password = "change-me"

[[proxy-group]]
name = "work"
type = "fallback"
proxies = ["office", "DIRECT"]
url = "https://www.gstatic.com/generate_204"
interval = 300

[rule]
list = [
  "DOMAIN-SUFFIX,corp.example.com,office",
  "DOMAIN-SUFFIX,github.com,work",
  "DOMAIN,registry.npmjs.org,work",
  "IP-CIDR,10.0.0.0/8,DIRECT,no-resolve",
  "IP-CIDR,192.168.0.0/16,DIRECT,no-resolve",
  "FINAL,DIRECT",
]

Test one domain that should use the proxy and one that should not, and compare the route shown in the connection log. See Rules for every rule type.

At this point every application that you configure to use 127.0.0.1:7890 follows your rules. Tools that ignore proxy settings need step 5.

Step 5: Route by process on Linux

On Linux, Enhanced Mode with the ebpf backend routes connections from every process, even those that ignore HTTP_PROXY, and lets rules match the process name:

[general]
route-mode = "rule"
log-level = "info"
port = 7890
protocols = "mixed"

[[proxy]]
name = "office"
type = "http"
server = "proxy.example.com"
port = 8080
username = "me"
password = "change-me"

[[proxy-group]]
name = "work"
type = "fallback"
proxies = ["office", "DIRECT"]
url = "https://www.gstatic.com/generate_204"
interval = 300

[rule]
list = [
  "PROCESS-NAME,git-remote-http,work",
  "PROCESS-NAME,cargo,work",
  "PROCESS-NAME,dockerd,work",
  "DOMAIN-SUFFIX,corp.example.com,office",
  "DOMAIN-SUFFIX,github.com,work",
  "IP-CIDR,10.0.0.0/8,DIRECT,no-resolve",
  "IP-CIDR,192.168.0.0/16,DIRECT,no-resolve",
  "FINAL,DIRECT",
]

[dns.tun]
mode = "fake-ip"

[enhanced-mode]
enable = true
type = "ebpf"
ip-version = "ipv4"

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

Enhanced Mode changes how the system routes traffic, so it needs root:

specola-core -t --config my.toml
sudo specola-core --config my.toml

When run with sudo, --config my.toml still resolves against your own ~/.config/specola/profiles/. Stop Core with Ctrl+C; it detaches everything it attached. Read Linux eBPF for requirements and troubleshooting, and DNS for why [dns.tun] matters.

When validation fails

The error names the field. The most common ones:

Message	Fix
inbound.type contains unsupported value 'https'	protocols accepts only mixed, http, socks5 and none
Unsupported top-level field 'inbound'	put port and protocols under [general]
Rule list requires an explicit FINAL target	end [rule].list with "FINAL,<target>"
Rule references unknown outbound: X	X must be DIRECT, REJECT, a proxy name or a group name, with the same capitalization
Global mode requires an existing proxy target	set global-proxy to an existing proxy or group
GEOIP rule requires a geoip resource	set [rule.cache].geoip, see Rules
enhanced-mode.type=tun is not supported on Linux	use type = "ebpf" on Linux

For the complete list of fields, see Full Configuration.