Skip to content

Proxies ​

Each [[proxy]] entry is one server that you operate or are authorized to use. Rules, proxy groups, global-proxy and dialer-proxy refer to it by its name. Specola ships with no proxies; the built-in targets DIRECT and REJECT always exist and are never declared.

toml
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.org"
port = 8080

Before you write rules for a new proxy, test it alone: set route-mode = "global" and global-proxy = "office". If Global fails, the problem is the proxy, not your rules.

How an entry is written ​

  • Every key of a proxy sits in its [[proxy]] table. Nested tables (tls, tls.reality, transport, headers) must be inline tables on one line: tls = { server-name = "proxy.example.org" }. A sub-table header such as [proxy.tls] is rejected with <path> must be an inline table.
  • [[proxy]] is lenient: a key Specola does not know is ignored without a warning. A misspelled key such as skip-cert-verfy or udp-over-relay simply has no effect. Copy key names from this page.
  • A known key with the wrong type (a number where a string is expected) is ignored with a warning in the log, unless the table below says the profile is rejected.
  • Key names are case-sensitive. alterId and udp_over_relay must be written exactly like that.

Common keys ​

KeyRequiredValue
nameyesunique name, see Names
typeyesone of the types
serveryeshost name or IP address, at most 255 characters
portyesinteger 1–65535
dialer-proxynoname of a proxy or group to connect through, see Proxy Chains. Write it with a hyphen; dialer_proxy is rejected
tlsnoinline table, see TLS
transportnoinline table, used by VMess and VLESS only, see Transports

Names ​

  • A name is unique across all proxies and proxy groups.
  • It cannot be DIRECT or REJECT, cannot contain a comma or ::, and cannot be empty or only spaces. :: is reserved for Specola's internal names.
  • Names are case-sensitive wherever they are referenced: a rule that targets Office does not reach a proxy named office.

Types ​

typeProtocolRequired keysTLSUDP
httpHTTP proxy (CONNECT)—optional, Reality allowedno
socks5SOCKS5—optional, Reality allowedonly with udp = true
ss or shadowsocksShadowsockscipher, passwordnot allowedyes
vmessVMess (AEAD)uuidoptionalonly with udp = true
vlessVLESSuuidoptional, Reality allowedyes, except with Vision
trojanTrojanpasswordalways onyes unless udp = false
anytlsAnyTLSpasswordalways onno
hysteria2Hysteria 2 (QUIC)passwordalways onyes
tuicTUIC v5 (QUIC)uuid, passwordalways onyes

vless, vmess and tuic are also accepted in upper case. Any other type is rejected with Unknown proxy type. The types ssh, mieru and sudoku are recognized but not included in the current build: a profile that uses them is rejected with Protocol is not included in the minimal build.

UDP ​

UDP routed to a proxy that cannot carry it is dropped. It does not fall back to DIRECT.

  • http and anytls never carry UDP.
  • socks5 and vmess carry UDP only with udp = true (default false). For SOCKS5 the server must support UDP ASSOCIATE.
  • trojan carries UDP by default; udp = false turns it off.
  • ss, vless, hysteria2 and tuic always carry UDP. They have no udp key; writing one has no effect.
  • VLESS with flow = "xtls-rprx-vision" cannot carry UDP. Shadowsocks with the 2022-blake3-chacha20-poly1305 cipher carries TCP only.

The local HTTP/SOCKS5 port carries TCP only, so UDP reaches a proxy only from Enhanced Mode, the router gateway, or DNS sent through a proxy.

HTTP ​

toml
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.org"
port = 8080
username = "me"
password = "change-me"
KeyDefaultValue
username, passwordnonesent as Proxy-Authorization: Basic
tlsoffadd it for an HTTPS proxy: tls = { server-name = "proxy.example.org" }. Reality is allowed; alpn is not
pathnonereplaces host:port in the CONNECT request line with this text. Only for servers that expect it
headersnoneinline table of extra request headers, string values
early-datafalsesend the first bytes of the connection together with CONNECT. The server must support it

SOCKS5 ​

toml
[[proxy]]
name = "lab"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "me"
password = "change-me"
udp = true
KeyDefaultValue
username, passwordnoneusername/password authentication
udpfalseallow UDP through UDP ASSOCIATE
tlsoffSOCKS5 over TLS. Reality is allowed; alpn is not
early-datafalsesend the first bytes together with the request. The server must support it. A value that is not a boolean rejects the profile

Shadowsocks ​

toml
[[proxy]]
name = "ss-home"
type = "ss"
server = "proxy.example.org"
port = 8388
cipher = "2022-blake3-aes-128-gcm"
password = "AAAAAAAAAAAAAAAAAAAAAA=="
KeyDefaultValue
cipherrequiredaes-128-gcm, aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm
passwordrequiredfor the 2022-* ciphers, the base64 key from the server: 16 bytes for aes-128, 32 bytes for aes-256
udp_over_relayfalseaccepted, but has no effect: UDP is always sent as UDP
  • A tls table is not allowed for Shadowsocks: any TLS setting rejects the profile.
  • 2022-blake3-chacha20-poly1305 loads with a warning and works for TCP; its UDP fails.
  • Any other cipher name loads with the warning cipher '...' may not be supported, and every connection through the proxy fails. Treat that warning as an error.
  • A 2022 key of the wrong length is not caught when the profile loads; connections fail.

VMess ​

toml
[[proxy]]
name = "vmess-home"
type = "vmess"
server = "proxy.example.org"
port = 443
uuid = "e6e1acfe-5b1e-4b1c-87c8-92beecb98ba2"
udp = true
tls = { server-name = "proxy.example.org" }
transport = { type = "ws", path = "/ws" }
KeyDefaultValue
uuidrequiredxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; another format rejects the profile
alterId0must be 0. Specola speaks AEAD VMess only: a positive value loads with a warning, and every connection fails. A negative value rejects the profile
cipherautoauto, aes-128-gcm, chacha20-poly1305, none (alias zero). auto is AES-128-GCM on x86-64 and ARM64, ChaCha20-Poly1305 elsewhere. An unknown value falls back to AES-128-GCM with a log warning
global-paddingfalseboolean
authenticated-lengthfalseboolean
udpfalseallow UDP
packet-encodingnonepacketaddr or xudp, for UDP. Another value is ignored with a warning
tlsoffoptional; alpn allowed
transportrawsee Transports

VLESS ​

toml
[[proxy]]
name = "vless-reality"
type = "vless"
server = "proxy.example.org"
port = 443
uuid = "b1479ae4-f64b-4b27-bdab-4fb0f4ecdba9"
flow = "xtls-rprx-vision"
tls = { server-name = "www.example.com", reality = { enabled = true, public-key = "public-key-from-your-server", short-id = "0123456789abcdef" } }
KeyDefaultValue
uuidrequiredUUID format; another format rejects the profile
flow"""" or xtls-rprx-vision. Another value loads, but every connection fails
encryptionnoneaccepted, but has no effect: Specola always sends VLESS without encryption
tlsoffoptional; alpn and Reality allowed
transportrawsee Transports

Vision (flow = "xtls-rprx-vision") needs TLS or Reality and the raw transport, and carries no UDP. A Vision proxy with another transport or without TLS loads, but its connections fail.

Trojan ​

toml
[[proxy]]
name = "trojan-home"
type = "trojan"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org" }
KeyDefaultValue
passwordrequireda password shorter than 8 characters loads with a warning
udptruefalse turns UDP off
tlsalways ontls.enabled = false is ignored with a warning. Without alpn, Trojan offers h2 and http/1.1

Trojan does not use transport.

AnyTLS ​

toml
[[proxy]]
name = "anytls-home"
type = "anytls"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org" }
KeyDefaultValue
passwordrequired
tlsalways onalpn is not allowed
idle_session_check_interval, idle_session_timeout, min_idle_session—accepted, but have no effect

Hysteria2 ​

toml
[[proxy]]
name = "hy2-home"
type = "hysteria2"
server = "proxy.example.org"
port = 443
password = "change-me"
obfs = "salamander"
obfs-password = "change-me-too"
tls = { server-name = "proxy.example.org" }
KeyDefaultValue
passwordrequired
obfsnonesalamander. Any other value turns obfuscation off without a warning
obfs-passwordnonethe Salamander key; read only together with obfs
down—accepted, but has no effect: Specola always tells the server its receive rate is unknown
ca—old spelling of tls.certificate-path; when present it wins over tls.certificate-path
tlsalways onalpn is not allowed; Hysteria2 always uses h3

TUIC ​

toml
[[proxy]]
name = "tuic-home"
type = "tuic"
server = "proxy.example.org"
port = 443
uuid = "e6e1acfe-5b1e-4b1c-87c8-92beecb98ba2"
password = "change-me"
congestion-control = "bbr"
tls = { server-name = "proxy.example.org", alpn = ["h3"] }
KeyDefaultValue
uuidrequiredUUID format; another format rejects the profile
passwordrequired
tlsalways onalpn allowed. Without alpn no ALPN is sent; most TUIC servers expect alpn = ["h3"]
congestion-controlcubiccubic, new_reno, bbr. Another value is ignored with a warning
udp-relay-modequicquic (UDP over QUIC streams) or native (QUIC datagrams)
heartbeat-interval"10s"a string: milliseconds ("10000") or a number with s or m ("10s", "1m"). Any other suffix counts as milliseconds except one starting with m: "500ms" means 500 minutes, write "500". A negative number means 10 s
request-timeout10000integer, milliseconds; also the QUIC handshake timeout. 0 means no timeout. A value that is not an integer silently means 10000
reduce-rttfalseresume earlier sessions with 0-RTT
fast-openfalsealso turns reduce-rtt on
disable-snifalsesend no SNI
ipnoneconnect to this address instead of resolving server
max-udp-relay-packet-size1200integer, bytes; kept within QUIC packet limits
max-open-streams100integer
tokennone64 hex characters (32 bytes) that replace the authentication token derived from the password. An invalid token is replaced by the derived one, with a log warning

Each TUIC key also accepts an underscore spelling (congestion_control), and heartbeat is an alias of heartbeat-interval.

Accepted keys that have no effect ​

These keys load without an error but change nothing today. Do not rely on them:

TypeKey
ssudp_over_relay
vlessencryption
hysteria2down
anytlsidle_session_check_interval, idle_session_timeout, min_idle_session
ss, vless, hysteria2, tuic, http, anytlsudp (not a key of these types)

Legacy TLS keys at the top level ​

Older profiles put TLS keys directly in the proxy: sni, alpn, skip-cert-verify, certificate, certificate-path, fingerprint. Specola ignores them there. When the proxy has no tls table (and always for TUIC), each one produces the warning uses legacy field '...'; move it under tls block. Move them into tls:

toml
# Before (ignored)
sni = "proxy.example.org"
skip-cert-verify = true

# After
tls = { server-name = "proxy.example.org", skip-cert-verify = true }

The only top-level TLS key that still works is Hysteria2's ca.

When problems show up ​

Some mistakes stop the profile from loading; others load and only fail when a connection uses the proxy.

Rejected when the profile loadsLoads, then connections fail
missing name, type, server or port; port out of rangeShadowsocks cipher outside the list, or a 2022 key of the wrong length
unknown or unsupported typeVMess alterId other than 0
missing required key of the typeVLESS flow other than "" and xtls-rprx-vision; Vision with a transport or without TLS
malformed uuid (VMess, VLESS, TUIC)alpn that conflicts with the transport (Transports)
duplicate or reserved nameReality with a transport other than raw or grpc
unsupported TLS key, or a TLS setting on Shadowsocks (TLS)gRPC multi-mode = true
a transport table without type or with an unknown type (even on types that ignore it)wrong password, key or certificate
tls.certificate-path file not found
invalid dialer-proxy (Proxy Chains)

Run --test-config --config <file> to see load errors and warnings without starting Core (see CLI). Warnings matter here: several of them mean "this proxy will not work".

Troubleshooting ​

  1. Test with Global first. If a proxy fails in Global mode, fix the proxy before touching rules.
  2. Read the warnings. A misspelled key is silent; a wrong value usually produces a warning in the log when the profile loads.
  3. UDP does not work (games, QUIC, voice): check the UDP table. SOCKS5 and VMess need udp = true; HTTP and AnyTLS never carry UDP; Vision has no UDP.
  4. TLS errors: check server-name and the certificate settings on the TLS page. skip-cert-verify = true is a test, not a fix.
  5. TUIC connects nowhere: add alpn = ["h3"] to tls.

Keep credentials out of shared repositories, logs and screenshots.

See also TLS, Transports, Proxy Groups and Proxy Chains.