Configuration
Choose local listeners, IPC CPU use, log output and optional pinned regions.
Pass --config /etc/swqos/swqos.toml when starting the agent. Restart the service after changing the file.
Example
# Optional: restrict the agent to these regions.
# upstreams = ["fra.sol.zerocopy.sh:443", "ams.sol.zerocopy.sh:443"]
[listen]
http = "127.0.0.1:8080"
quic = "127.0.0.1:4433"
ipc = "/run/swqos/swqos.sock"
ipc_busy_poll = true
[log]
level = "info,rustls=error"
format = "text"upstreams is a top-level key. In TOML, a key written after a [table] header belongs to that table, so keep upstreams above [listen].
Options
| Option | Value | Purpose |
|---|---|---|
upstreams | Array of "host:port" strings | Optional pinned regions; omit for automatic region selection |
listen.http | IP address and port | Local HTTP and JSON-RPC; defaults to 127.0.0.1:8080 |
listen.quic | IP address and port | Local QUIC; defaults to 127.0.0.1:4433 |
listen.ipc | Unix socket path | Set an explicit path, or "" to disable IPC |
listen.ipc_busy_poll | Boolean | Defaults to true; see Busy polling |
log.level | Log filter | Defaults to info,rustls=error |
log.format | text or json | Defaults to text |
The agent rejects unknown options and values of the wrong type. Use only the options above.
Listeners
Keep HTTP and QUIC on loopback. They do not authenticate local callers: anyone who can reach them can submit transactions and incur charges on your account. Both listeners take an IP address and port.
IPC socket
Set ipc to a path in a directory the agent can write. The service example creates /run/swqos; the agent does not create the directory itself.
The socket has mode 0660. Give client accounts access through the swqos group as described in installation. Keep the path shorter than 108 bytes.
For multiple agents on one host, give each a different socket path, HTTP port and QUIC port.
Busy polling
| Setting | Behavior | Tradeoff |
|---|---|---|
true (default) | Polls continuously while any IPC client is connected | Uses one CPU core, even when the client is idle |
false | Sleeps when idle and wakes on submissions | Lower idle CPU use, with wake-up latency after quiet periods |
With no IPC client connected, both modes sleep. This option does not affect HTTP or QUIC. You can use systemd's CPUAffinity= to keep the agent off your application's CPU cores. Custom IPC clients must implement doorbells in either mode.
Logging
Logs go to standard output. Use info, warn, debug or a filter such as info,rustls=error for level. The RUST_LOG environment variable overrides this setting. An invalid filter prevents startup.
Use format = "json" for one JSON object per line. Some log lines contain a site= code instead of a descriptive message; include those lines unchanged when contacting support.
Pinned regions
Leave upstreams unset for automatic region selection. Set it only when you want the agent to use a fixed list:
upstreams = ["fra.sol.zerocopy.sh:443", "ams.sol.zerocopy.sh:443"]Each entry must be a regional host under sol.zerocopy.sh with a port, not an IP address or the anycast name sol.zerocopy.sh. See Regions and failover before pinning.