General
[general] decides how Core routes traffic, what it logs and where it listens. Every key is optional; a key you leave out takes its default, and a profile without [general] at all is valid.
[general]
route-mode = "rule"
global-proxy = ""
log-level = "info"
log-file = true
port = 7890
protocols = "mixed"
allow-lan = false
api-listen = ""Fields
| Field | Type | Default | Accepted values |
|---|---|---|---|
route-mode | string | "rule" | rule, global, direct (lower case) |
global-proxy | string | "" | a proxy, a proxy group, DIRECT or REJECT; must exist when route-mode = "global" |
log-level | string | "info" | trace, debug, info, warn (or warning), error, critical, off; case does not matter |
log-file | boolean | true | false stops writing log files |
port | integer | 7890 | 1–65535; 0 turns the local port off |
protocols | string or array | "mixed" | mixed, socks5 (alias socks), http, none |
allow-lan | boolean | false | true listens on 0.0.0.0 instead of 127.0.0.1 |
api-listen | string | "" | IP:port, localhost:port or [IPv6]:port; empty means no TCP control API |
ipv6 | boolean | false | accepted and saved, but nothing in Core reads it |
Any other key is an error: Unknown general field '<key>'. api-secret from older profiles is dropped without a message.
Route mode
| Mode | What happens |
|---|---|
rule | each connection is matched against [route].rules; the first match wins |
global | every connection goes to global-proxy |
direct | every connection goes direct; proxies, groups and rules are loaded but not used |
[general]
route-mode = "global"
global-proxy = "work" # a proxy or a proxy group
[[proxy]]
name = "work"
type = "socks5"
server = "proxy.example.org"
port = 1080route-mode = "global"with an empty or unknownglobal-proxyfails to load:Global mode requires an existing proxy target. In the other modesglobal-proxyis not checked.RuleorGLOBALis an error (Unknown mode); write the mode in lower case.- Switching the mode in the app changes the running Core only; it does not edit the file. When you re-activate the profile, the mode written in the file is applied only if you changed it in the file.
A useful order when setting up: direct to prove the local setup works, global to prove one proxy works, then rule.
Logging
log-level sets how much Core logs. It filters both the log files and the in-memory log that the app's Logs page shows (the last 5000 entries). off silences both.
log-file = false stops writing files; the in-memory log keeps working.
Log files are written to the log folder:
| Platform | Log folder |
|---|---|
| Windows | %LOCALAPPDATA%\Specola\Logs; %ProgramData%\Specola\Logs when Core runs as the Windows service |
| macOS | ~/Library/Logs/com.specola.Specola |
| Linux | $XDG_STATE_HOME/specola/log, by default ~/.local/state/specola/log |
- Set the environment variable
SPECOLA_LOG_DIRbefore Core starts to use another folder. It moves the logs only. - Release builds write one file per day, named
specola_YYYY-MM-DD, start a new one at midnight and keep the last 7. - Until a profile is loaded, Core logs at
info.
Local port
port and protocols open one local port for programs that have a proxy setting.
[general]
port = 7890
protocols = "mixed" # SOCKS5 and HTTP on the same port[general]
port = 1080
protocols = ["socks5"] # SOCKS5 onlyprotocols | Accepts |
|---|---|
mixed | SOCKS5 and HTTP |
socks5 or socks | SOCKS5 only |
http | HTTP only, including CONNECT |
none | nothing; the port is not opened |
- An array lists several values:
["socks5", "http"]is the same asmixed. - An array must not be empty (use
"none"), must not repeat a protocol (["mixed", "http"]repeats HTTP), andnonecannot be combined with anything. - There is no
httpsvalue. HTTPS sites work throughhttpbecause it includesCONNECT. port = 0orprotocols = "none"leaves only Enhanced Mode, with no explicit proxy port.- A port below 1024 loads with a warning; it needs administrator or root rights to open.
What the port accepts
The port tells SOCKS5 and HTTP apart by the first byte of each connection.
| Client speaks | Supported | Not supported |
|---|---|---|
| SOCKS5 | CONNECT to an IPv4 address, IPv6 address or host name | username/password authentication, UDP ASSOCIATE, BIND, SOCKS4 |
| HTTP | CONNECT host:port (HTTPS and any other TCP), plain requests with an absolute http:// URL, or a path plus a Host header | proxy authentication (Proxy-Authorization is removed), keep-alive across requests |
- The port carries TCP only. UDP from programs reaches Specola only through Enhanced Mode.
- A plain HTTP request is answered with
Connection: close: one request per connection. - Request headers larger than 64 KiB are refused with
431. - A host name sent through SOCKS5 or HTTP is used for domain rules as written; Core does not need to resolve it first.
Point a client at the port:
curl -x http://127.0.0.1:7890 https://example.com
curl -x socks5h://127.0.0.1:7890 https://example.com
export ALL_PROXY=socks5h://127.0.0.1:7890Core never changes the operating system's proxy settings. The app has a switch that stops and starts the port at run time; a port you stopped there stays stopped when the profile is re-activated.
[general.inbound]
Older profiles put the same two keys in a sub-table. It still works:
[general.inbound]
port = 7890
protocols = "mixed"Use one place or the other. Writing port (or protocols) in both is an error: Configure general.port only once; do not also use general.inbound. Any other key in the sub-table is an error.
LAN access
allow-lan = true binds the port to 0.0.0.0, so other devices on your network can use it. It binds IPv4 only.
- The port has no authentication. Anyone who can reach it uses your proxies. Allow it only on a trusted network, and restrict it with a firewall.
- Connections from other devices carry no process, so process rules never match them. Route them with
SRC-IP-CIDRinstead (see Rules).
Control API
The desktop app always talks to Core over a local channel: a named pipe on Windows, a Unix socket on macOS and Linux. That needs no configuration (see CLI). api-listen additionally opens a TCP listener, so a script or an app on another machine can control this Core. It speaks the same MessagePack-RPC protocol, not HTTP; see Control API.
[general]
api-listen = "0.0.0.0:9090" # or "127.0.0.1:9090", "[::1]:9090", "localhost:9090"- The address must be an IP literal or
localhost, followed by a port from 1 to 65535. A host name such asrouter.lan:9090is an error:general.api-listen must be IP:port, localhost:port, or [IPv6]:port. - Whatever address it binds, Core serves only peers on this computer or a private network: loopback,
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10(CGNAT, Tailscale),169.254.0.0/16,fc00::/7andfe80::/10, also as IPv4-mapped IPv6. Any other peer is disconnected as it connects and logged. - There is no authentication and no encryption. Every device on those networks can read your traffic statistics, change routing and edit profiles. Never forward this port to the internet.
license.*andcore.shutdownare refused over TCP; they work only over the local channel.- The listener accepts up to 8 connections at a time.
- Changing or removing
api-listenapplies when you re-activate the profile. Core opens the new listener first, then keeps the old one serving for about two seconds so a client that sent the change still receives the end of its reply. If the new address cannot be opened (the port is in use, the address is not on this computer), the activation fails and nothing changes.
On a Linux router started with --gateway, Core also opens a control listener on its LAN address (port 9090) before any profile is loaded; see CLI.
ipv6
general.ipv6 is parsed and saved, and the app shows it, but nothing in Core uses it. IPv6 DNS answers are controlled by [dns].ipv6, captured IPv6 traffic by [enhanced-mode].ip-version.
Applying changes
Re-activating the profile applies every [general] change to the running Core; no restart is needed.
| Change | Effect |
|---|---|
log-level, log-file | applied at once |
route-mode, global-proxy | applied to new connections |
port, protocols, allow-lan | the listener moves; connections already open keep running |
api-listen | the TCP listener moves as described above |
On Linux with Enhanced Mode on eBPF, a listener change rebuilds the whole runtime, which closes open connections. If any step fails, the earlier steps are undone. A profile that does not load leaves the running one untouched.
Errors
| Message | Cause |
|---|---|
Unknown general field '<key>' | a misspelled or removed key |
general.port must be an integer | port = "7890" |
Invalid mixed port: <n> | port outside 0–65535 |
inbound.type contains unsupported value '<v>' (expected mixed, socks5, http, or none) | a wrong protocols value, https included |
inbound.type contains duplicate protocol '<v>' | a protocol listed twice, such as ["mixed", "http"] |
inbound.type none cannot be combined with another protocol | ["none", "http"] |
inbound.type array must not be empty; use 'none' explicitly | protocols = [] |
Unknown mode: <v> (should be rule/global/direct) | wrong route-mode, or wrong case |
Global mode requires an existing proxy target | global-proxy missing or unknown in global mode |
Unknown log level: <v> | wrong log-level |
general.api-listen must be IP:port, localhost:port, or [IPv6]:port | a host name, a missing port or port 0 |
Use general.port and general.api-listen | mixed-port or external-controller from older profiles |
The messages about protocols say inbound.type because Core reads protocols under that internal name.
Names from older versions
| Old | Current |
|---|---|
mixed-port | port (an error) |
external-controller | api-listen (an error) |
top-level [inbound] | port and protocols in [general] (an error) |
protocols = ["http", "https"] | protocols = "http" (an error) |
api-secret | nothing: the control API has no secret (dropped silently) |
Troubleshooting
- Programs cannot connect to the port. Check that
protocolsincludes the client's protocol and that nothing else uses the port; a port that cannot be opened makes the activation fail with the reason. A client set to SOCKS4, or to SOCKS5 with a password, is refused. - Another device cannot reach the port. Set
allow-lan = true, use this computer's IPv4 address, and allow the port in the firewall. - A remote client cannot reach the control API. The peer must be on a private network: a client on a public address is disconnected (look for
refused TCP clientin the log). Over a VPN, use an address in100.64.0.0/10or another private range. - No log files. Check
log-fileandlog-level, and look in the log folder for your platform, or inSPECOLA_LOG_DIRif it is set.
See also Full Configuration for every section, and CLI for running Core yourself.
