Configuration

Risuko stores configuration in two JSON files in the config directory:

• system.json — Engine options such as dir, split, doh-*, and rpc-secret
• user.json — App preferences plus a fixed set of user-scope engine keys

The desktop app creates both files on first run. The CLI and Node.js API never create them; missing files or keys fall back to built-in defaults in memory.

The engine does not merge the two files wholesale. It starts from system.json, copies only the user-scope keys from user.json, then applies engine-overrides. Any other key in user.json is ignored by the engine, even if it has the same name as an engine option.

User ConfigCopy Anchor Link

These user.json keys override system.json when the engine starts:

rpc-host, m3u8-output-format, keep-seeding, bt-create-subfolder, bt-enable-upnp, bt-upnp-lease, bt-encryption-policy, bt-listen-v6, bt-enable-lsd, purge-record-on-start, task-routing-rules, file-category-dirs, max-worker-retries, usenet-profiles, usenet-archive-limits, usenet-cleanup-mode, pbh-enable, pbh-listen-port, pbh-rpc-secret, and proxy (flattened into all-proxy / p2p-*).

Config Directory LocationsCopy Anchor Link

<name> depends on the host:

The standalone CLI and Node.js API therefore share the desktop app's directory on fresh installs, but keep using dev.risuko.app if it already exists.

Reading ConfigurationCopy Anchor Link

CLICopy Anchor Link

# List all settings
risuko config list

# Get a specific value
risuko config get dir

# JSON output
risuko config list --json

Node.jsCopy Anchor Link

import risuko from "@risuko/risuko-js";

const options = await risuko.getGlobalOption();
console.log(options.dir);
console.log(options["max-concurrent-downloads"]);

Writing ConfigurationCopy Anchor Link

CLICopy Anchor Link

# User-scope keys can be set directly
risuko config set rpc-host 0.0.0.0
risuko config set keep-seeding true

# Engine keys go through engine-overrides (replaces the whole object)
risuko config set engine-overrides '{"dir":"/home/user/downloads","max-concurrent-downloads":5}'

Values are parsed as JSON; anything that isn't valid JSON is stored as a plain string.

Node.jsCopy Anchor Link

import risuko from "@risuko/risuko-js";

await risuko.changeGlobalOption({
  dir: "/home/user/downloads",
  "max-concurrent-downloads": "5",
});

changeGlobalOption changes the running engine only; nothing is written to the config files, so the values are lost at stopEngine.

Option ReferenceCopy Anchor Link

GeneralCopy Anchor Link

Desktop AppCopy Anchor Link

These keys are read by the Tauri desktop app. They are stored in user.json and are not part of the engine's JSON-RPC surface.

ConnectionCopy Anchor Link

Speed LimitingCopy Anchor Link

HTTPCopy Anchor Link

ProxyCopy Anchor Link

See the Proxy Support guide for URL schemes, scopes, and bypass syntax.

DNS over HTTPSCopy Anchor Link

When enabled, hostnames are resolved by POSTing RFC 8484 wire-format queries (application/dns-message) to a DoH endpoint instead of using the system resolver. A and AAAA records are queried together and the answers cached in memory (smallest record TTL, clamped to 30–3600 s, plus a 5 s negative cache).

This applies to every HTTP client in the engine — downloads, m3u8 segments, RSS, WebDAV/S3 uploads, BitTorrent HTTP trackers, and UPnP. It does not cover BitTorrent UDP trackers/DHT or FTP/SFTP/ED2K/ADC connections, which still resolve through the system. SOCKS5h proxies keep resolving names proxy-side.

ReliabilityCopy Anchor Link

Low-Speed Auto-RecoveryCopy Anchor Link

A separate watchdog from lowest-speed-limit. The renderer's EngineClient samples active task speeds, and any task whose downloadSpeed stays under low-speed-threshold for 5 consecutive polling ticks is force-paused and resumed (with a 30-second per-task cooldown between recovery cycles).

StorageCopy Anchor Link

BitTorrentCopy Anchor Link

The DHT (BEP-5) is always enabled and runs as a dual-stack client when an IPv6 socket can be bound. The BitTorrent TCP listener binds listen-port (21301 by default; for a range or list such as 6881-6889 the first port is used), falling back to a random port if it cannot be bound. dht-listen-port is not bound by anything yet (the DHT shares the listener's UDP port); it is only validated by the health check. bt-force-encryption maps to bt-encryption-policy require when the policy is unset or prefer; an explicit plaintext or require policy wins. The legacy aria2 keys enable-dht, enable-dht6, enable-peer-exchange, bt-enable-lpd (use bt-enable-lsd), bt-exclude-tracker, follow-torrent, allow-overwrite, and continue have been removed from the engine defaults because nothing read them. They are still accepted if a client or saved config sends them, but have no effect, and continue and follow-torrent are no longer synced. bt-load-saved-metadata (default true) makes a magnet reuse the .torrent saved by bt-save-metadata instead of resolving its metadata over the network again.

RPCCopy Anchor Link

Media (yt-dlp)Copy Anchor Link

RSSCopy Anchor Link

See the RSS Feeds guide for the full workflow. RSS subscriptions, items, and rules are persisted via the desktop app's storage. Each feed is polled on its own interval (default 1800 s, minimum 60 s).

The old rss-auto-update and rss-update-interval keys are no longer used or listed by the app.

Task RoutingCopy Anchor Link

See the Task Routing guide.

Completion ScriptsCopy Anchor Link

Run a script after every download finishes (success or failure). Per-task overrides are accepted via the desktop app's task options. See the Completion Scripts guide.

Usenet / NZBCopy Anchor Link

See the Usenet and NZB Downloads guide for the provider setup and recovery workflow. These settings are used for new NZB tasks; task options snapshot the selected profile reference, cleanup policy, and any confirmed archive-limit override.

Provider profiles use camel-case fields inside the usenet-profiles array:

[
  {
    "id": "primary",
    "name": "Primary provider",
    "host": "news.example.net",
    "port": 563,
    "securityMode": "implicit-tls",
    "enabled": true,
    "priority": 0,
    "maxConnections": 4,
    "allowPlain": false,
    "updatedAt": 1765000000000
  }
]

Valid securityMode values are implicit-tls, starttls, and plain. Plain NNTP also needs allowPlain: true; the app requires a separate user acknowledgement before it saves that state. Lower priority values run first.

The following option keys may be set through risuko.addNzb. The current Add Task form uses the global Usenet archive policy and does not expose per-task archive controls yet:

Task options must not include a username, password, archive password, or credential-bearing provider object. Risuko removes those values before it saves the task or returns it through RPC.

Saved CredentialsCopy Anchor Link

Legacy P2P / IPC stacksCopy Anchor Link

The old adc-hub, adc-nick, gnutella-cache, and g2-cache keys are no longer listed by the app and nothing reads them. Gnutella and G2 downloads connect directly to the peer in the URI, and ADC / DC transfers are not implemented.

External EngineCopy Anchor Link

By default the desktop app boots an embedded engine in-process. Switch to External Engine mode to point the UI at a separately running risuko serve (or any aria2-compatible RPC server). When enabled, the embedded engine is not started; all add_uri, polling, and config writes are routed over JSON-RPC.

LoggingCopy Anchor Link

Startup-only KeysCopy Anchor Link

The following keys are read once when the engine starts. Changing them at runtime is accepted (the value is persisted) but does not take effect until the engine is restarted (Quit & relaunch the desktop app, or restart risuko serve):

dht-listen-port, ed2k-enable-kad, ed2k-kad-port, ed2k-port, listen-port, rpc-host, rpc-listen-port, rpc-secret, pbh-enable, pbh-listen-port, pbh-rpc-secret, bt-max-peers-per-torrent, bt-max-outstanding-per-peer, bt-ban-corrupt-peers, bt-ban-corrupt-strikes, bt-enable-upnp, bt-upnp-lease, bt-enable-lsd, bt-encryption-policy, bt-listen-v6.

All other keys are hot-reloaded on the next task or polling cycle.