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.
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.org"
port = 8080Before 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 asskip-cert-verfyorudp-over-relaysimply 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.
alterIdandudp_over_relaymust be written exactly like that.
Common keys
| Key | Required | Value |
|---|---|---|
name | yes | unique name, see Names |
type | yes | one of the types |
server | yes | host name or IP address, at most 255 characters |
port | yes | integer 1–65535 |
dialer-proxy | no | name of a proxy or group to connect through, see Proxy Chains. Write it with a hyphen; dialer_proxy is rejected |
tls | no | inline table, see TLS |
transport | no | inline table, used by VMess and VLESS only, see Transports |
Names
- A name is unique across all proxies and proxy groups.
- It cannot be
DIRECTorREJECT, 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
Officedoes not reach a proxy namedoffice.
Types
type | Protocol | Required keys | TLS | UDP |
|---|---|---|---|---|
http | HTTP proxy (CONNECT) | — | optional, Reality allowed | no |
socks5 | SOCKS5 | — | optional, Reality allowed | only with udp = true |
ss or shadowsocks | Shadowsocks | cipher, password | not allowed | yes |
vmess | VMess (AEAD) | uuid | optional | only with udp = true |
vless | VLESS | uuid | optional, Reality allowed | yes, except with Vision |
trojan | Trojan | password | always on | yes unless udp = false |
anytls | AnyTLS | password | always on | no |
hysteria2 | Hysteria 2 (QUIC) | password | always on | yes |
tuic | TUIC v5 (QUIC) | uuid, password | always on | yes |
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.
httpandanytlsnever carry UDP.socks5andvmesscarry UDP only withudp = true(defaultfalse). For SOCKS5 the server must supportUDP ASSOCIATE.trojancarries UDP by default;udp = falseturns it off.ss,vless,hysteria2andtuicalways carry UDP. They have noudpkey; writing one has no effect.- VLESS with
flow = "xtls-rprx-vision"cannot carry UDP. Shadowsocks with the2022-blake3-chacha20-poly1305cipher 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
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.org"
port = 8080
username = "me"
password = "change-me"| Key | Default | Value |
|---|---|---|
username, password | none | sent as Proxy-Authorization: Basic |
tls | off | add it for an HTTPS proxy: tls = { server-name = "proxy.example.org" }. Reality is allowed; alpn is not |
path | none | replaces host:port in the CONNECT request line with this text. Only for servers that expect it |
headers | none | inline table of extra request headers, string values |
early-data | false | send the first bytes of the connection together with CONNECT. The server must support it |
SOCKS5
[[proxy]]
name = "lab"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "me"
password = "change-me"
udp = true| Key | Default | Value |
|---|---|---|
username, password | none | username/password authentication |
udp | false | allow UDP through UDP ASSOCIATE |
tls | off | SOCKS5 over TLS. Reality is allowed; alpn is not |
early-data | false | send the first bytes together with the request. The server must support it. A value that is not a boolean rejects the profile |
Shadowsocks
[[proxy]]
name = "ss-home"
type = "ss"
server = "proxy.example.org"
port = 8388
cipher = "2022-blake3-aes-128-gcm"
password = "AAAAAAAAAAAAAAAAAAAAAA=="| Key | Default | Value |
|---|---|---|
cipher | required | aes-128-gcm, aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-aes-128-gcm, 2022-blake3-aes-256-gcm |
password | required | for the 2022-* ciphers, the base64 key from the server: 16 bytes for aes-128, 32 bytes for aes-256 |
udp_over_relay | false | accepted, but has no effect: UDP is always sent as UDP |
- A
tlstable is not allowed for Shadowsocks: any TLS setting rejects the profile. 2022-blake3-chacha20-poly1305loads 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
[[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" }| Key | Default | Value |
|---|---|---|
uuid | required | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx; another format rejects the profile |
alterId | 0 | must be 0. Specola speaks AEAD VMess only: a positive value loads with a warning, and every connection fails. A negative value rejects the profile |
cipher | auto | auto, 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-padding | false | boolean |
authenticated-length | false | boolean |
udp | false | allow UDP |
packet-encoding | none | packetaddr or xudp, for UDP. Another value is ignored with a warning |
tls | off | optional; alpn allowed |
transport | raw | see Transports |
VLESS
[[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" } }| Key | Default | Value |
|---|---|---|
uuid | required | UUID format; another format rejects the profile |
flow | "" | "" or xtls-rprx-vision. Another value loads, but every connection fails |
encryption | none | accepted, but has no effect: Specola always sends VLESS without encryption |
tls | off | optional; alpn and Reality allowed |
transport | raw | see 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
[[proxy]]
name = "trojan-home"
type = "trojan"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org" }| Key | Default | Value |
|---|---|---|
password | required | a password shorter than 8 characters loads with a warning |
udp | true | false turns UDP off |
tls | always on | tls.enabled = false is ignored with a warning. Without alpn, Trojan offers h2 and http/1.1 |
Trojan does not use transport.
AnyTLS
[[proxy]]
name = "anytls-home"
type = "anytls"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org" }| Key | Default | Value |
|---|---|---|
password | required | |
tls | always on | alpn is not allowed |
idle_session_check_interval, idle_session_timeout, min_idle_session | — | accepted, but have no effect |
Hysteria2
[[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" }| Key | Default | Value |
|---|---|---|
password | required | |
obfs | none | salamander. Any other value turns obfuscation off without a warning |
obfs-password | none | the 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 |
tls | always on | alpn is not allowed; Hysteria2 always uses h3 |
TUIC
[[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"] }| Key | Default | Value |
|---|---|---|
uuid | required | UUID format; another format rejects the profile |
password | required | |
tls | always on | alpn allowed. Without alpn no ALPN is sent; most TUIC servers expect alpn = ["h3"] |
congestion-control | cubic | cubic, new_reno, bbr. Another value is ignored with a warning |
udp-relay-mode | quic | quic (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-timeout | 10000 | integer, milliseconds; also the QUIC handshake timeout. 0 means no timeout. A value that is not an integer silently means 10000 |
reduce-rtt | false | resume earlier sessions with 0-RTT |
fast-open | false | also turns reduce-rtt on |
disable-sni | false | send no SNI |
ip | none | connect to this address instead of resolving server |
max-udp-relay-packet-size | 1200 | integer, bytes; kept within QUIC packet limits |
max-open-streams | 100 | integer |
token | none | 64 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:
| Type | Key |
|---|---|
ss | udp_over_relay |
vless | encryption |
hysteria2 | down |
anytls | idle_session_check_interval, idle_session_timeout, min_idle_session |
ss, vless, hysteria2, tuic, http, anytls | udp (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:
# 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 loads | Loads, then connections fail |
|---|---|
missing name, type, server or port; port out of range | Shadowsocks cipher outside the list, or a 2022 key of the wrong length |
unknown or unsupported type | VMess alterId other than 0 |
| missing required key of the type | VLESS 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 name | Reality 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
- Test with Global first. If a proxy fails in Global mode, fix the proxy before touching rules.
- Read the warnings. A misspelled key is silent; a wrong value usually produces a warning in the log when the profile loads.
- 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. - TLS errors: check
server-nameand the certificate settings on the TLS page.skip-cert-verify = trueis a test, not a fix. - TUIC connects nowhere: add
alpn = ["h3"]totls.
Keep credentials out of shared repositories, logs and screenshots.
See also TLS, Transports, Proxy Groups and Proxy Chains.
