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

Environment	Path
macOS	`~/Library/Application Support/dev.risuko.app`
Linux	`~/.config/dev.risuko.app`
Windows	`%APPDATA%\dev.risuko.app`
Desktop App	Managed by Tauri (platform-specific app data)
Node.js API	Configurable via `EngineConfig.configDir`

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"'

Values must be valid JSON. Strings need double quotes inside quotes: '"value"'

Node.js

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

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

Option Reference

General

Key	Default	Description
`dir`	OS default	Default download directory
`max-concurrent-downloads`	`5`	Maximum parallel download tasks
`continue`	`true`	Resume interrupted downloads
`purge-record-on-start`	`false`	When the engine starts, drop completed/stopped task records from the session. On-disk files for stopped torrent tasks are preserved (the librqbit orphan-purge step is told to keep files for those info-hashes); HTTP/FTP/etc. payloads on disk are never touched

Connection

Key	Default	Description
`split`	`16`	Connections per download (HTTP/HTTPS); ignored when the file is smaller than `min-split-size` or the server doesn't support `Range`
`min-split-size`	`1M`	Minimum segment size before the file is split (bytes; accepts `K`/`M`/`G` suffixes)

Speed Limiting

Key	Default	Description
`max-overall-download-limit`	`0`	Global download speed limit (bytes/s, 0 = unlimited)
`max-overall-upload-limit`	`0`	Global upload speed limit (bytes/s)
`max-download-limit`	`0`	Per-task download speed limit

HTTP

Key	Default	Description
`user-agent`	Chrome UA string	Default user agent string
`referer`	—	Default HTTP referer
`header`	—	Default HTTP headers (array)
`all-proxy`	—	Proxy server URL. Accepts `http://`, `socks5://`, or `socks5h://` (use `socks5h` to resolve hostnames through the proxy). `https://` proxies are not supported
`load-cookies`	—	Path to a Netscape/Mozilla format `cookies.txt` (also accepts curl/wget output) loaded into the per-task cookie jar
`netrc-path`	`~/.netrc` (`%USERPROFILE%\_netrc` on Windows)	Override the `.netrc` file used to inject HTTP Basic auth when a URL has no embedded credentials
`no-netrc`	`false`	Skip `.netrc` lookup entirely

Reliability

Key	Default	Description
`connect-timeout`	`60`	Connect timeout in seconds for HTTP/HTTPS/FTP
`lowest-speed-limit`	`0`	Stalled-transfer threshold in bytes/s. If the EMA stays below this for `lowest-speed-limit-timeout`, the worker is aborted (and restarted when auto-retry is enabled). `0` disables the watchdog
`lowest-speed-limit-timeout`	`30`	How many seconds the transfer must stay below `lowest-speed-limit` before it is considered stalled
`uri-selector`	`feedback`	Mirror selection strategy when a task has multiple URIs: `feedback` (drop slow/failing mirrors), `inorder` (try left-to-right), or `adaptive` (prefer fastest)

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 3 consecutive polling ticks is force-paused and resumed (with a 30-second per-task cooldown between recovery cycles).

Key	Default	Description
`auto-detect-low-speed-tasks`	`false`	Master switch. When `false`, the recovery loop never runs
`low-speed-threshold`	`20`	Speed threshold in KB/s below which a task counts toward the strike count

Pause/resume only revives a single stalled TCP connection — useful for HTTP/HTTPS, FTP/SFTP, and HTTP-segment streams (m3u8, YouTube). Peer-swarm protocols (BitTorrent, ED2K, ADC, Gnutella, G2, giFT) are explicitly excluded from this recovery: pause tears down peer connections, aborts in-flight tracker announces and choke negotiations, and the swarm spends minutes warming up again. Tasks whose kind is not in {http, ftp, youtube, m3u8}, or whose kind is missing, are skipped.

Storage

Key	Default	Description
`file-allocation`	`falloc`	Disk reservation strategy. `falloc` reserves real blocks via `fallocate(2)` (Linux) or `fcntl(F_PREALLOCATE)` (macOS), falling back to `set_len`. `trunc` only sets the file length. `none` lets writes grow the file as needed. The aria2 alias `prealloc` is accepted as a synonym for `falloc`
`auto-file-renaming`	`true`	When the target output file already exists, append `.1`, `.2`, … instead of overwriting
`remote-time`	`false`	Stamp the local file mtime from the server's `Last-Modified` header on completion (per-task)
`use-remote-file-time`	—	UI/global preference mirrored into per-task `remote-time` when set
`m3u8-output-format`	`ts`	Container produced after concatenating HLS segments (`ts` keeps the original transport stream; other values trigger a remux)
`file-category-dirs`	—	Per-category default directory overrides (object keyed by category id, e.g. `{ "video": "/downloads/video" }`); applied as a fallback when no routing rule matches

BitTorrent

Key	Default	Description
`keep-seeding`	`false`	Seed until manually stopped (overrides `seed-time` / `seed-ratio`)
`seed-ratio`	`0`	Stop seeding at this ratio (0 = no ratio limit)
`seed-time`	`0`	Seed for this many minutes after completing (0 = no time limit)
`bt-tracker`	—	Additional tracker URLs (comma-separated)
`bt-max-peers-per-torrent`	`100`	Max concurrent peer connections per torrent (engine restart)
`bt-max-outstanding-per-peer`	`128`	Max pipelined chunk requests per peer (engine restart)
`bt-enable-upnp`	`true`	Map the listen port on the router via UPnP IGD (engine restart)
`bt-upnp-lease`	`300`	UPnP mapping lease in seconds (engine restart)
`bt-enable-lsd`	`true`	BEP-14 Local Service Discovery via multicast (engine restart)
`bt-encryption-policy`	`prefer`	MSE/PE policy: `plaintext`, `prefer`, or `require` (engine restart)
`bt-listen-v6`	`false`	Also bind an IPv6 TCP listener on the same port (engine restart)
`bt-create-subfolder`	`true`	When `true`, multi-file torrents and magnets are placed under `<dir>/<name>/`. When `false`, files are written directly into `dir`. Single-file torrents are unaffected. Read on each task add (no restart needed); accepted as a per-task option override

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

Key	Default	Description
`rpc-listen-port`	`16800`	RPC server port
`rpc-host`	`127.0.0.1`	RPC bind address (set to `0.0.0.0` for LAN access)
`rpc-secret`	—	RPC authentication token

YouTube (yt-dlp)

Key	Default	Description
`youtube-format`	yt-dlp default	yt-dlp `-f` format selector (e.g. `bestvideo+bestaudio/best`, `mp4`)

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.

Key	Default	Description
`rss-auto-update`	—	Enable periodic feed polling (boolean; controlled from the RSS panel)
`rss-update-interval`	—	Polling interval in minutes between automatic refreshes

Task Routing

See the Task Routing guide.

Key	Default	Description
`task-routing-rules`	`[]`	Array of `{ id, label, pattern, dir, enabled }` rules. The first enabled rule whose case-insensitive glob `pattern` matches the inferred filename wins; `dir` overrides the download directory and `label` is exposed as the task tag. Falls through to `file-category-dirs` then global `dir`

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.

Key	Default	Description
`completion-script-enabled`	`false`	Master switch. When false, no script runs even if `command` is set
`completion-script-command`	—	Absolute path to the executable to invoke (no shell parsing)
`completion-script-args`	—	Whitespace-tokenised arguments template. Supported placeholders inside any token: `{path}` (final file path), `{hash}` (task GID), `{status}` (`complete` / `error` / `cancelled`). The same values are also exported as `RISUKO_PATH`, `RISUKO_HASH`, `RISUKO_STATUS` env vars
`completion-script-timeout-ms`	`30000`	Per-invocation timeout in milliseconds. Clamped to `1000`–`300000` (5 minutes). stdout/stderr captured into the log are truncated to 8 KiB

Saved Credentials

Key	Default	Description
`saved-credentials`	`[]`	Non-secret credential profile metadata (id, label, scope, username). Passwords and SSH private keys are stored separately in the OS keychain (`risuko-credentials` service) and never written to `user.json`

Legacy P2P / IPC stacks

Key	Default	Description
`adc-hub`	—	Default ADC / DC hub URI (`adc(s)://`, `dchub://`, `nmdc://`) used as a hint when a file URI doesn't include one
`adc-nick`	—	Nickname presented to the ADC / DC hub
`gnutella-cache`	—	GWebCache URLs (comma-separated) used to bootstrap Gnutella ultrapeers
`g2-cache`	—	Bootstrap caches for the Gnutella2 (G2) network
`gift-enabled`	`false`	Allow `gift://` URIs to be forwarded to a local `giftd` daemon
`gift-host`	`127.0.0.1`	giFT IPC bind address
`gift-port`	`1213`	giFT IPC port

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

Key	Default	Description
`external-engine-enabled`	`false`	Skip the embedded engine and connect to a remote RPC server instead
`external-engine-host`	—	Hostname or IP of the remote RPC server
`external-engine-port`	`16800`	Port of the remote RPC server
`external-engine-secret`	—	Token to send as `token:<secret>` on each call

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

Configuration

Config Directory Locations

Reading Configuration

CLI

Node.js

Writing Configuration

CLI

Node.js

Option Reference

General

Connection

Speed Limiting

HTTP

Reliability

Low-Speed Auto-Recovery

Storage

BitTorrent

RPC

YouTube (yt-dlp)

RSS

Task Routing

Completion Scripts

Saved Credentials

Legacy P2P / IPC stacks

External Engine

Startup-only Keys

On this page