Skip to content

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.

toml
[general]
route-mode = "rule"
global-proxy = ""
log-level = "info"
log-file = true
port = 7890
protocols = "mixed"
allow-lan = false
api-listen = ""

Fields ​

FieldTypeDefaultAccepted values
route-modestring"rule"rule, global, direct (lower case)
global-proxystring""a proxy, a proxy group, DIRECT or REJECT; must exist when route-mode = "global"
log-levelstring"info"trace, debug, info, warn (or warning), error, critical, off; case does not matter
log-filebooleantruefalse stops writing log files
portinteger78901–65535; 0 turns the local port off
protocolsstring or array"mixed"mixed, socks5 (alias socks), http, none
allow-lanbooleanfalsetrue listens on 0.0.0.0 instead of 127.0.0.1
api-listenstring""IP:port, localhost:port or [IPv6]:port; empty means no TCP control API
ipv6booleanfalseaccepted 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 ​

ModeWhat happens
ruleeach connection is matched against [route].rules; the first match wins
globalevery connection goes to global-proxy
directevery connection goes direct; proxies, groups and rules are loaded but not used
toml
[general]
route-mode = "global"
global-proxy = "work"        # a proxy or a proxy group

[[proxy]]
name = "work"
type = "socks5"
server = "proxy.example.org"
port = 1080
  • route-mode = "global" with an empty or unknown global-proxy fails to load: Global mode requires an existing proxy target. In the other modes global-proxy is not checked.
  • Rule or GLOBAL is 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:

PlatformLog 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_DIR before 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.

toml
[general]
port = 7890
protocols = "mixed"          # SOCKS5 and HTTP on the same port
toml
[general]
port = 1080
protocols = ["socks5"]       # SOCKS5 only
protocolsAccepts
mixedSOCKS5 and HTTP
socks5 or socksSOCKS5 only
httpHTTP only, including CONNECT
nonenothing; the port is not opened
  • An array lists several values: ["socks5", "http"] is the same as mixed.
  • An array must not be empty (use "none"), must not repeat a protocol (["mixed", "http"] repeats HTTP), and none cannot be combined with anything.
  • There is no https value. HTTPS sites work through http because it includes CONNECT.
  • port = 0 or protocols = "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 speaksSupportedNot supported
SOCKS5CONNECT to an IPv4 address, IPv6 address or host nameusername/password authentication, UDP ASSOCIATE, BIND, SOCKS4
HTTPCONNECT host:port (HTTPS and any other TCP), plain requests with an absolute http:// URL, or a path plus a Host headerproxy 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:

bash
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:7890

Core 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:

toml
[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-CIDR instead (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.

toml
[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 as router.lan:9090 is 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::/7 and fe80::/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.* and core.shutdown are refused over TCP; they work only over the local channel.
  • The listener accepts up to 8 connections at a time.
  • Changing or removing api-listen applies 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.

ChangeEffect
log-level, log-fileapplied at once
route-mode, global-proxyapplied to new connections
port, protocols, allow-lanthe listener moves; connections already open keep running
api-listenthe 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 ​

MessageCause
Unknown general field '<key>'a misspelled or removed key
general.port must be an integerport = "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' explicitlyprotocols = []
Unknown mode: <v> (should be rule/global/direct)wrong route-mode, or wrong case
Global mode requires an existing proxy targetglobal-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]:porta host name, a missing port or port 0
Use general.port and general.api-listenmixed-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 ​

OldCurrent
mixed-portport (an error)
external-controllerapi-listen (an error)
top-level [inbound]port and protocols in [general] (an error)
protocols = ["http", "https"]protocols = "http" (an error)
api-secretnothing: the control API has no secret (dropped silently)

Troubleshooting ​

  1. Programs cannot connect to the port. Check that protocols includes 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.
  2. Another device cannot reach the port. Set allow-lan = true, use this computer's IPv4 address, and allow the port in the firewall.
  3. 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 client in the log). Over a VPN, use an address in 100.64.0.0/10 or another private range.
  4. No log files. Check log-file and log-level, and look in the log folder for your platform, or in SPECOLA_LOG_DIR if it is set.

See also Full Configuration for every section, and CLI for running Core yourself.