Configuration

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

• system.json — System-level defaults (created on first run)
• user.json — User overrides

User settings take precedence over system defaults.

Config Directory Locations

Reading Configuration

CLI

# List all settings
risuko config list

# Get a specific value
risuko config get dir

# JSON output
risuko config list --json

Node.js

import { getGlobalOption } from "@risuko/risuko-js";

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

Writing Configuration

CLI

risuko config set dir '"/home/user/downloads"'
risuko config set max-concurrent-downloads '"5"'

Node.js

import { changeGlobalOption } from "@risuko/risuko-js";

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

Option Reference

General

Desktop App

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.

Connection

Speed Limiting

HTTP

Proxy

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

DNS over HTTPS

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.

Reliability

Low-Speed Auto-Recovery

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).

Storage

BitTorrent

The DHT (BEP-5) is always enabled and runs as a dual-stack client when an IPv6 socket can be bound. The BitTorrent listener uses an ephemeral port; the legacy aria2 keys listen-port, dht-listen-port, enable-dht, enable-dht6, enable-peer-exchange, and bt-enable-lpd are accepted for backwards compatibility but currently have no effect.

RPC

YouTube (yt-dlp)

RSS

See the RSS Feeds guide for the full workflow. RSS subscriptions, items, and rules are persisted via the desktop app's storage; the keys below are user-level UI preferences.

Task Routing

See the Task Routing guide.

Completion Scripts

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 / NZB

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 Credentials

Legacy P2P / IPC stacks

External Engine

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.

Logging

Startup-only Keys

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-listen-port, rpc-secret, pbh-enable, pbh-listen-port, pbh-rpc-secret, bt-max-peers-per-torrent, bt-max-outstanding-per-peer, bt-upload-rate-limit, 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.