Control API
Not a REST API
Despite this page's address, Core has no HTTP or REST API: no /api/v1 routes, no secret and no OpenAPI file. The control API is MessagePack-RPC.
Everything the desktop app does goes through Core's control API: switching profiles, choosing group members, reading connections and logs, editing proxies and rules. Scripts and other clients speak the same protocol as the app.
The schema is the api/*.toml files in the source tree, one file per service. They list every method and every field, in wire order. This page explains how to connect and how to read them.
Transports
| Transport | Address | Opened | Who can connect |
|---|---|---|---|
| Named pipe (Windows) | \\.\pipe\specola | always | see CLI |
| Unix socket (macOS, Linux) | /tmp/specola.sock | always | the user who started Core (mode 0600) |
| TCP | [general].api-listen | when the profile sets it | loopback and private-network peers |
| TCP, router mode | LAN address, port 9090 | with --gateway, before any profile | loopback and private-network peers |
--ipc-endpointmoves the local endpoint.- The TCP listener speaks the same protocol, not HTTP. It may bind any address, but serves only loopback,
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,100.64.0.0/10,169.254.0.0/16,fc00::/7andfe80::/10; other peers are disconnected as they connect. - There is no authentication and no encryption on any transport.
license.*andcore.shutdownwork only over the local endpoint; over TCP they fail with-32003.- Each listener accepts up to 8 connections at a time.
- Changing
api-listenmoves the TCP listener when the profile is re-activated; Core does not restart.
Wire format
Standard MessagePack-RPC plus server streaming. Every message is one MessagePack array. Messages are written back to back with no length prefix; a MessagePack value delimits itself.
request [0, msgid, method, [req]] optional 5th element: {0: timeout_us, 1: window}
response [1, msgid, error, result] error = nil | [code, message]
notification [2, method, [req]]
stream item [3, msgid, item] server -> client, before the final response
cancel [4, msgid] client -> server
credit [5, msgid, n] client -> server: n more stream items
goaway [6, last_msgid, reason] server -> client: Core is shutting downmsgidis an unsigned 32-bit number chosen by the client, unique among its open requests.- Every method takes exactly one struct and returns one struct, so the params array always has one element:
[req]. methodis the wire name, such asproxy.selectGroupMember. Thealiasesinapi/*.tomlare names for the app's internal bridge, not wire names.
Structs are positional arrays
A struct is an array of its fields in declaration order, not a map. Field names are not sent.
| Schema type | On the wire |
|---|---|
| struct | array of all its fields, in the order of api/*.toml; the empty struct Empty is [] |
T? (optional) | the value, or nil |
T[] | array |
map<K, V> | map |
| enum | the index of the value: RouteMode = ["direct", "rule", "global"], so rule is 1 |
| variant | [case id, value] |
string, bool, integers, f64 | the MessagePack type of the same kind |
A request must carry every field. default in the schema is the initial value of generated clients; it is not filled in for you on the wire. Adding, removing or reordering a field breaks the contract, which is why the handshake compares a hash of the whole schema.
For example, api/proxy.toml declares
[[struct]]
name = "ProxyDelayReq"
fields = [
{ id = 0, name = "proxy_id", type = "string" },
{ id = 1, name = "protocol", type = "string", default = "tcp" },
{ id = 2, name = "url", type = "string" },
{ id = 3, name = "timeout_ms", type = "u32", default = 5000 },
{ id = 4, name = "expected_status", type = "string", default = "200-399" },
]so a delay test is the request [0, 7, "proxy.testDelay", [["office", "tcp", "", 5000, "200-399"]]].
Limits
- A message larger than 4 MiB closes the connection.
- At most 32 requests may be open per connection; more fail with
-32012. - TCP connections use keepalive; a peer that vanished is dropped after about 90 seconds.
Handshake
Call sys.hello first on every connection:
HelloReq [contract_version, client_name, contract_hash, min_supported_version]
HelloResp [contract_version, server_name, contract_hash, min_supported_version]contract_versionandmin_supported_versioncome fromapi/rpcgen.toml(both3today).contract_hashis a 64-bit hash of the whole schema. Core answers-32600when it differs from its own. Compute it from theapifolder of the same source tree as your Core:bashpython3 -c "import sys; sys.path.insert(0, 'tool/rpcgen'); from pathlib import Path; \ from schema import load; print(hex(load([Path('api')]).hash))"api/api.lockrecords the contract of the last release; itshashmatches only a Core built from that release.Core does not refuse calls made without
sys.hello, but a client built from another schema misreads every struct. Always shake hands.
The app then calls profile.setDirectory with the user's Profiles folder. A client that does not call it works with Core's own Profiles folder (none for the Windows service).
Streams
A stream is a request answered by any number of [3, msgid, item] messages and then a normal response that ends it (nil, or an error). Streams and calls interleave freely on one connection.
- Snapshots.
watch*methods send a complete snapshot at once and then newer ones; items are not patches. - Flow control. A request may carry a window (meta key
1): Core sends at most that many items until the client grants more with[5, msgid, n]. Without a window the stream is not limited; Core waits while the socket is full. - Cancel.
[4, msgid]ends a stream or abandons a call. - Deadlines.
timeout_us(meta key0) makes Core answer-32010itself once it passes. - Shutdown. When Core exits it sends GOAWAY: running calls finish, streams end with
-32013, new requests are refused, and connections close after 3 seconds at the latest.
Readiness
| Available | Methods |
|---|---|
| as soon as the listener is open | sys.*, core.*, profile.*, license.*, overview.*, ssh.*, gateway.* |
| once a profile is parsed | general.getConfig |
| once Core runs a profile | everything else |
Earlier calls fail with -32002. core.watchStartup reports progress until Core is ready. While a profile is being activated, every request except sys.hello fails with -32006 and business streams end; reopen them after the activation's last item.
Errors
| Code | Meaning |
|---|---|
-32600 | protocol error: malformed message, or a different contract in sys.hello |
-32601 | unknown method |
-32602 | invalid parameters: wrong struct shape, or a value Core rejects |
-32603 | internal error |
-32002 | Core is not ready for this method yet |
-32003 | forbidden: license.* or core.shutdown over TCP, a peer outside the private network, or a missing licence |
-32004 | not found |
-32005 | conflict, for example a stale expected_revision |
-32006 | busy: a profile activation is running |
-32007 | unavailable, for example the DNS resolver is not running |
-32010 | deadline exceeded |
-32011 | cancelled |
-32012 | overloaded: too many open requests, or a stream consumer fell behind |
-32013 | Core is shutting down |
A minimal client
Any MessagePack library works. This Python sketch (pip install msgpack) connects, shakes hands, reads the health, runs a delay test and follows an activation:
import socket, msgpack
CONTRACT_HASH = 0x0 # the value printed by the command under "Handshake"
sock = socket.socket(socket.AF_UNIX) # Linux, macOS
sock.connect("/tmp/specola.sock")
# TCP: sock = socket.create_connection(("192.168.1.2", 9090))
# Windows: sock = open(r"\\.\pipe\specola", "r+b", buffering=0), with write()/read() below
unpacker = msgpack.Unpacker()
last_id = 0
def messages():
while True:
for message in unpacker:
yield message
data = sock.recv(65536)
if not data:
raise ConnectionError("Core closed the connection")
unpacker.feed(data)
def call(method, req):
"""Unary call; returns the result struct as a list."""
global last_id
last_id += 1
sock.sendall(msgpack.packb([0, last_id, method, [req]]))
for kind, msgid, *rest in messages():
if kind == 1 and msgid == last_id:
error, result = rest
if error is not None:
raise RuntimeError(error) # [code, message]
return result
def stream(method, req):
"""Stream; yields each item until Core ends the stream."""
global last_id
last_id += 1
sock.sendall(msgpack.packb([0, last_id, method, [req]]))
for kind, msgid, *rest in messages():
if msgid != last_id:
continue
if kind == 3:
yield rest[0]
elif kind == 1:
if rest[0] is not None:
raise RuntimeError(rest[0])
return
print(call("sys.hello", [3, "my-script", CONTRACT_HASH, 3]))
ok, ready, state, message = call("core.getHealth", [])
proxy_id, ok, delay_ms, observed_at_ms, message = call(
"proxy.testDelay", ["office", "tcp", "", 5000, "200-399"])
call("routing.setMode", [1, None]) # RouteMode index 1 = rule
# ActivateProfileReq [name, refresh_geo]; items are ProfileActivationEvent
# [name, stage, message, terminal, succeeded, previous_profile_retained]
for event in stream("profile.activateProfile", ["home", False]):
print(event[2])
if event[3]:
print("succeeded" if event[4] else "failed")The source tree also has a generator, tool/rpcgen, that writes typed C++, C# and Swift clients from api/*.toml (python3 tool/rpcgen/rpcgen.py --api-dir api --lang csharp --out-dir out); the C++ runtime is header-only in common/include/rpc.
Methods
Unary unless marked stream. The request and result structs of each method are in the named api/*.toml file.
sys (sys.toml)
| Method | Does |
|---|---|
sys.hello | contract handshake; call first |
sys.ping | returns the server time |
core (core.toml)
| Method | Does |
|---|---|
core.getHealth | whether Core is ready, and its state |
core.getVersion | Core version, platform, OS and total memory |
core.getMemory | Core's memory use |
core.probeHost | this computer's public IP, its location and UDP NAT type, measured without a proxy (Tools) |
core.locateHosts | GeoIP location of up to 64 hosts, without a proxy |
core.shutdown | stops Core; local endpoint only |
core.checkUpdate | looks for a newer release now |
core.startUpdate | downloads and verifies the update package |
core.cancelUpdate | cancels the download |
core.installUpdate | starts the verified installer, then stops Core |
core.watchStartup stream | start-up progress until Core is ready |
core.watchUpdate stream | update availability, download progress and install state |
core.watchLogs stream | buffered log entries after a sequence number, then new ones |
general (general.toml)
| Method | Does |
|---|---|
general.getConfig | route mode, log level, api-listen, port and protocols of the loaded profile |
general.getProfileSettings | the profile values the app's Settings page shows |
general.updateProfileSettings | writes the given values into the active profile file and re-activates it |
profile (profile.toml)
| Method | Does |
|---|---|
profile.setDirectory | binds the caller's Profiles folder; call once after connecting |
profile.getProfiles | lists the profiles |
profile.importProfile | copies a profile file into the Profiles folder |
profile.createProfile | writes a new profile; does not activate it |
profile.renameProfile | renames a profile |
profile.removeProfile | removes a profile |
profile.activateProfile stream | loads or re-applies a profile; items report each stage, the last one says whether it succeeded |
profile.createModule | creates an empty module file |
profile.deleteModule | moves a module file away and takes it off every profile |
profile.setProfileModules | sets the modules a profile applies, in order |
profile.watchProfiles stream | declared, not served: -32601 |
profile.createSubscriptionProfile | declared, not served: -32601 |
profile.updateSubscriptionProfile | declared, not served: -32601 |
profile.refreshSubscriptionProfile | declared, not served: -32601 |
routing (routing.toml)
| Method | Does |
|---|---|
routing.getState | route mode, selected global target and listener state |
routing.setMode | switches the route mode of the running Core; the file is not changed |
routing.setEnhanced | turns Enhanced Mode on or off by re-applying the profile with that change |
routing.setSshForward | turns SSH port forwards on or off; see Tools |
routing.watchState stream | routing state at once and on every change |
proxy (proxy.toml)
| Method | Does |
|---|---|
proxy.listProxies | every proxy with its type, address and health |
proxy.listProxyGroups | every group with its members and selection |
proxy.getProxy | one proxy |
proxy.getProxyGroup | one group |
proxy.getCatalog | proxies and groups in one snapshot |
proxy.watchCatalog stream | the catalog at once and after every change |
proxy.selectGlobal | switches to global mode through a proxy or group |
proxy.selectGroupMember | chooses the member of a select group |
proxy.testDelay | one HTTP request through a proxy, timed (Tools) |
proxy.runNatTest | STUN through a proxy's UDP path (Tools) |
proxy.getSource | a proxy as written in the profile file |
proxy.save | validates a proxy, writes it into the profile file and applies it |
proxy.delete | removes a proxy from the file; refused while a group or rule uses it |
proxy.saveGroup | writes a group into the file and applies it |
proxy.deleteGroup | removes a group; refused while a rule or group uses it |
proxy.reorder | rewrites the [[proxy]] tables in a new order |
proxy.reorderGroups | rewrites the [[proxy-group]] tables in a new order |
rules (rules.toml)
| Method | Does |
|---|---|
rules.list | the rules of the loaded profile and its modules |
rules.replace | validates a rule list, writes it into the profile file and applies it |
rules.getFile | route.rules of one profile or module file |
rules.replaceFile | writes route.rules of one profile or module file |
rules.getProvider | records of a rule set, page by page |
rules.replaceProvider | replaces the records of an inline rule set |
rules.setProviderSource | changes the URL of a remote rule set |
rules.listGeo | categories of geosite.dat or geoip.dat |
rules.getGeo | entries of one geo category |
rules.match | which rule a destination hits, without DNS and without a process |
dns (dns.toml)
| Method | Does |
|---|---|
dns.getDnsSnapshot | the DNS cache |
dns.watchDnsCache stream | the cache at once and after changes |
dns.queryDns | resolves a name with Core's resolver (A or AAAA) |
dns.lookupDns | resolves a name as a captured query would be, and says which rule, resolver and proxy answered |
dns.getDnsConfig | the DNS settings in effect |
dns.flushDnsCache | empties the DNS cache |
dns.flushFakeIpCache | forgets the Fake-IP mappings |
connections (connections.toml)
| Method | Does |
|---|---|
connections.listConnections | open connections with process, rule and proxy |
connections.watchConnections stream | connection changes in batches |
connections.closeConnection | closes one connection |
connections.closeAllConnections | closes every connection |
telemetry and overview (telemetry.toml, overview.toml)
| Method | Does |
|---|---|
telemetry.getTraffic | traffic counters and rates |
telemetry.getProxyState | route mode, selection and listener state |
telemetry.watchTraffic stream | a traffic sample every interval_ms |
telemetry.watchProxyState stream | the proxy state at once and on change |
overview.getOverview | the data of the app's Overview page |
overview.watchOverview stream | the overview at once and on change |
system_proxy (system_proxy.toml)
| Method | Does |
|---|---|
system_proxy.startLocalProxy | opens the local port of [general] |
system_proxy.stopLocalProxy | closes it; it stays closed across re-activation |
system_proxy.getListeners | the local port and DNS listener with their addresses |
system_proxy.getState | declared, not served: -32601 |
system_proxy.watchState stream | declared, not served: -32601 |
system_proxy.setEnabled | declared, not served: -32601 |
None of these changes the operating system's proxy settings.
ssh (ssh.toml)
| Method | Does |
|---|---|
ssh.probe | runs read-only inspection commands on a server (Tools) |
ssh.watchServer stream | keeps a session to a server and samples its load |
ssh.scanHostKey | reads a server's host key without logging in |
ssh.listConfigHosts | the Host aliases of the ssh config on the Core machine |
ssh.listFiles | lists a directory over SFTP |
ssh.makeDirectory | creates a directory |
ssh.removeFile | removes a file or directory |
ssh.moveFile | renames or moves a file |
ssh.readFile | reads up to 1 MiB of a file |
ssh.writeFile | uploads a file in chunks of up to 1 MiB |
ssh.closeFiles | closes the SFTP session kept for a server |
license and gateway (license.toml, gateway.toml)
| Method | Does |
|---|---|
license.getStatus | licence state; local endpoint only, like every license.* method |
license.activateOnline | activates with a licence key |
license.activateOffline | activates with a signed token issued for this device |
license.refresh | refreshes the licence with the server |
license.deactivate | releases this computer's activation |
gateway.getDevices | LAN devices seen in router mode |
The methods marked "declared, not served" are in the schema but no service in this Core answers them.
