Skip to content

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 ​

TransportAddressOpenedWho can connect
Named pipe (Windows)\\.\pipe\specolaalwayssee CLI
Unix socket (macOS, Linux)/tmp/specola.sockalwaysthe user who started Core (mode 0600)
TCP[general].api-listenwhen the profile sets itloopback and private-network peers
TCP, router modeLAN address, port 9090with --gateway, before any profileloopback and private-network peers
  • --ipc-endpoint moves 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::/7 and fe80::/10; other peers are disconnected as they connect.
  • There is no authentication and no encryption on any transport.
  • license.* and core.shutdown work only over the local endpoint; over TCP they fail with -32003.
  • Each listener accepts up to 8 connections at a time.
  • Changing api-listen moves 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 down
  • msgid is 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].
  • method is the wire name, such as proxy.selectGroupMember. The aliases in api/*.toml are 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 typeOn the wire
structarray 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
enumthe index of the value: RouteMode = ["direct", "rule", "global"], so rule is 1
variant[case id, value]
string, bool, integers, f64the 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

toml
[[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_version and min_supported_version come from api/rpcgen.toml (both 3 today).

  • contract_hash is a 64-bit hash of the whole schema. Core answers -32600 when it differs from its own. Compute it from the api folder of the same source tree as your Core:

    bash
    python3 -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.lock records the contract of the last release; its hash matches 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 key 0) makes Core answer -32010 itself 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 ​

AvailableMethods
as soon as the listener is opensys.*, core.*, profile.*, license.*, overview.*, ssh.*, gateway.*
once a profile is parsedgeneral.getConfig
once Core runs a profileeverything 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 ​

CodeMeaning
-32600protocol error: malformed message, or a different contract in sys.hello
-32601unknown method
-32602invalid parameters: wrong struct shape, or a value Core rejects
-32603internal error
-32002Core is not ready for this method yet
-32003forbidden: license.* or core.shutdown over TCP, a peer outside the private network, or a missing licence
-32004not found
-32005conflict, for example a stale expected_revision
-32006busy: a profile activation is running
-32007unavailable, for example the DNS resolver is not running
-32010deadline exceeded
-32011cancelled
-32012overloaded: too many open requests, or a stream consumer fell behind
-32013Core 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:

python
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) ​

MethodDoes
sys.hellocontract handshake; call first
sys.pingreturns the server time

core (core.toml) ​

MethodDoes
core.getHealthwhether Core is ready, and its state
core.getVersionCore version, platform, OS and total memory
core.getMemoryCore's memory use
core.probeHostthis computer's public IP, its location and UDP NAT type, measured without a proxy (Tools)
core.locateHostsGeoIP location of up to 64 hosts, without a proxy
core.shutdownstops Core; local endpoint only
core.checkUpdatelooks for a newer release now
core.startUpdatedownloads and verifies the update package
core.cancelUpdatecancels the download
core.installUpdatestarts the verified installer, then stops Core
core.watchStartup streamstart-up progress until Core is ready
core.watchUpdate streamupdate availability, download progress and install state
core.watchLogs streambuffered log entries after a sequence number, then new ones

general (general.toml) ​

MethodDoes
general.getConfigroute mode, log level, api-listen, port and protocols of the loaded profile
general.getProfileSettingsthe profile values the app's Settings page shows
general.updateProfileSettingswrites the given values into the active profile file and re-activates it

profile (profile.toml) ​

MethodDoes
profile.setDirectorybinds the caller's Profiles folder; call once after connecting
profile.getProfileslists the profiles
profile.importProfilecopies a profile file into the Profiles folder
profile.createProfilewrites a new profile; does not activate it
profile.renameProfilerenames a profile
profile.removeProfileremoves a profile
profile.activateProfile streamloads or re-applies a profile; items report each stage, the last one says whether it succeeded
profile.createModulecreates an empty module file
profile.deleteModulemoves a module file away and takes it off every profile
profile.setProfileModulessets the modules a profile applies, in order
profile.watchProfiles streamdeclared, not served: -32601
profile.createSubscriptionProfiledeclared, not served: -32601
profile.updateSubscriptionProfiledeclared, not served: -32601
profile.refreshSubscriptionProfiledeclared, not served: -32601

routing (routing.toml) ​

MethodDoes
routing.getStateroute mode, selected global target and listener state
routing.setModeswitches the route mode of the running Core; the file is not changed
routing.setEnhancedturns Enhanced Mode on or off by re-applying the profile with that change
routing.setSshForwardturns SSH port forwards on or off; see Tools
routing.watchState streamrouting state at once and on every change

proxy (proxy.toml) ​

MethodDoes
proxy.listProxiesevery proxy with its type, address and health
proxy.listProxyGroupsevery group with its members and selection
proxy.getProxyone proxy
proxy.getProxyGroupone group
proxy.getCatalogproxies and groups in one snapshot
proxy.watchCatalog streamthe catalog at once and after every change
proxy.selectGlobalswitches to global mode through a proxy or group
proxy.selectGroupMemberchooses the member of a select group
proxy.testDelayone HTTP request through a proxy, timed (Tools)
proxy.runNatTestSTUN through a proxy's UDP path (Tools)
proxy.getSourcea proxy as written in the profile file
proxy.savevalidates a proxy, writes it into the profile file and applies it
proxy.deleteremoves a proxy from the file; refused while a group or rule uses it
proxy.saveGroupwrites a group into the file and applies it
proxy.deleteGroupremoves a group; refused while a rule or group uses it
proxy.reorderrewrites the [[proxy]] tables in a new order
proxy.reorderGroupsrewrites the [[proxy-group]] tables in a new order

rules (rules.toml) ​

MethodDoes
rules.listthe rules of the loaded profile and its modules
rules.replacevalidates a rule list, writes it into the profile file and applies it
rules.getFileroute.rules of one profile or module file
rules.replaceFilewrites route.rules of one profile or module file
rules.getProviderrecords of a rule set, page by page
rules.replaceProviderreplaces the records of an inline rule set
rules.setProviderSourcechanges the URL of a remote rule set
rules.listGeocategories of geosite.dat or geoip.dat
rules.getGeoentries of one geo category
rules.matchwhich rule a destination hits, without DNS and without a process

dns (dns.toml) ​

MethodDoes
dns.getDnsSnapshotthe DNS cache
dns.watchDnsCache streamthe cache at once and after changes
dns.queryDnsresolves a name with Core's resolver (A or AAAA)
dns.lookupDnsresolves a name as a captured query would be, and says which rule, resolver and proxy answered
dns.getDnsConfigthe DNS settings in effect
dns.flushDnsCacheempties the DNS cache
dns.flushFakeIpCacheforgets the Fake-IP mappings

connections (connections.toml) ​

MethodDoes
connections.listConnectionsopen connections with process, rule and proxy
connections.watchConnections streamconnection changes in batches
connections.closeConnectioncloses one connection
connections.closeAllConnectionscloses every connection

telemetry and overview (telemetry.toml, overview.toml) ​

MethodDoes
telemetry.getTraffictraffic counters and rates
telemetry.getProxyStateroute mode, selection and listener state
telemetry.watchTraffic streama traffic sample every interval_ms
telemetry.watchProxyState streamthe proxy state at once and on change
overview.getOverviewthe data of the app's Overview page
overview.watchOverview streamthe overview at once and on change

system_proxy (system_proxy.toml) ​

MethodDoes
system_proxy.startLocalProxyopens the local port of [general]
system_proxy.stopLocalProxycloses it; it stays closed across re-activation
system_proxy.getListenersthe local port and DNS listener with their addresses
system_proxy.getStatedeclared, not served: -32601
system_proxy.watchState streamdeclared, not served: -32601
system_proxy.setEnableddeclared, not served: -32601

None of these changes the operating system's proxy settings.

ssh (ssh.toml) ​

MethodDoes
ssh.proberuns read-only inspection commands on a server (Tools)
ssh.watchServer streamkeeps a session to a server and samples its load
ssh.scanHostKeyreads a server's host key without logging in
ssh.listConfigHoststhe Host aliases of the ssh config on the Core machine
ssh.listFileslists a directory over SFTP
ssh.makeDirectorycreates a directory
ssh.removeFileremoves a file or directory
ssh.moveFilerenames or moves a file
ssh.readFilereads up to 1 MiB of a file
ssh.writeFileuploads a file in chunks of up to 1 MiB
ssh.closeFilescloses the SFTP session kept for a server

license and gateway (license.toml, gateway.toml) ​

MethodDoes
license.getStatuslicence state; local endpoint only, like every license.* method
license.activateOnlineactivates with a licence key
license.activateOfflineactivates with a signed token issued for this device
license.refreshrefreshes the licence with the server
license.deactivatereleases this computer's activation
gateway.getDevicesLAN devices seen in router mode

The methods marked "declared, not served" are in the schema but no service in this Core answers them.