Plugin host configuration
Reference for host identity, authentication, operation permissions, and transfer limits.
Plugin hosts
pluginHosts registers independent plugin-host deployments whose operations can
produce playable audio. See Playing audio through plugins for behavior,
lifecycle and security. Every entry is validated at startup. Duplicate IDs fail startup. You can manage
these entries with remedia-server plugins instead of editing the file.
This fragment belongs alongside auth or users in a complete configuration.
{
"pluginHosts": [
{
"id": "youtubei-peer",
"url": "http://localhost:5678",
"allowHttp": true,
"operations": ["discord-player.source/source.search", "discord-player.source/source.stream"]
}
]
}The configured origin is automatically trusted for host-served media, including on localhost or a
LAN. Additional mediaOrigins are optional. HTTPS always works; HTTP requires allowHttp: true.
Use { "pluginId": "example.source", "operation": "source.stream", "replaySafe": true }
only when retries are safe. Discovery never grants permission to advertised operations.
| Field | Type | Default / validation |
|---|---|---|
id | string | Required, unique; 1-128 letters, digits, ., _ or -, starting alphanumeric. Stable deployment identity used by clients |
enabled | boolean | true. When false the host keeps its configuration but is not registered at startup. Requests naming it fail with plugin_host_disabled. Still fully validated |
url | string | Required HTTP(S) origin without credentials, path, query or fragment. Must be https unless allowHttp is true |
auth | object | { "type": "none" } by default, or { "type": "bearer", "token": "..." } with a 16-4096 byte token without spaces or control characters |
allowHttp | boolean | false. Permits http: endpoints and media origins for this host |
mediaOrigins | array | Extra origins whose media is fetched without credentials. The endpoint origin is always included |
allowExternalMedia | boolean | false. Allows descriptor URLs on other origins, played under the ordinary media.* policy and FFmpeg HTTP input |
operations[] | array | Required, 1-256 unique PLUGIN/OPERATION strings, or objects with pluginId, operation, and optional replaySafe (default false) |
limits.requestTimeoutMs | integer | 10000; 1-300,000. Connect and total deadline for each discovery or execute request, and media response headers |
limits.discoveryTtlMs | integer | 60000; 1,000-3,600,000. Discovery refresh interval |
limits.maxRequestBytes | integer | 65536; 64-16,777,216. Serialized execute request, including the opaque input |
limits.maxResponseBytes | integer | 65536; 256-16,777,216. Discovery and execute response bodies |
limits.maxPendingOperations | integer | 8; 1-1,024. Concurrent operation preparations per host |
limits.maxActiveStreams | integer | 8; 1-1,024. Concurrent media transfers per host |
limits.maxMediaBytes | integer | 1 GiB; 1,024-68,719,476,736. A transfer exceeding it fails |
limits.mediaIdleTimeoutMs | integer | 15000; 1-300,000. Maximum wait for the next media chunk while the decoder is consuming |
limits.mediaBufferBytes | integer | 262144; 4,096-16,777,216. Per-stream queue between the network and the decoder |
limits.maxAttempts | integer | 2; 1-3. Total attempts for replaySafe operations |
replaySafe declares that executing the operation again has no side effects, which authorizes
automatic retries and fresh resolution of expired grants. Leave it false for anything else.
operations[] is the single authoritative allowlist, for playback and for
operation forwarding: remote clients can invoke only these pairs, even
if the host advertises more, and they discover them with plugin.list without configuring the host
themselves. Forwarded results are also bounded by limits.maxMessageBytes. Set it, and the host's
limits.maxResponseBytes, high enough for the largest result you expect.
The pluginHosts fields are part of the generated JSON Schema and RemediaConfigSchema. The strict
Rust loader remains authoritative for resolved values such as environment references.