rvbox/docs/configuration.md

RVBox v1 configuration contract

RVBox v1 uses TOML 1.0 for daemon configuration. The normative annotated examples are examples/server.toml and examples/client.toml. They list every supported v1 knob, with the routing, persistence, and safety limits first in each section. The runnable Windows-first deployment example is examples/client.windows.toml; omitted entries use the defaults documented by the all-knob client reference.

Loading and precedence

• rvbox-server --config PATH and rvbox --config PATH load one UTF-8 TOML file. There is no implicit merge, runtime rewrite, or hot reload in v1. On Windows, the SCM service command line holds the canonical explicit config path; omitting it during installation selects the resolved %ProgramData%\RVBox\client.toml; first run creates its annotated template and the service reports not-ready until routing is valid rather than connecting to a placeholder server.
• Precedence is compiled default, then TOML, then an explicitly supplied CLI flag. Flags exist for operationally important scalar keys; they use the same validation as TOML. RVBox does not implicitly import configuration from environment variables.
• Unknown keys, duplicate keys/tables, type mismatches, invalid UTF-8, and values outside documented ranges are startup errors. Parsing never silently substitutes a default for a present invalid value.
• Durations are quoted Go-style duration strings such as "250ms", "15m", and "720h". Byte sizes and counts are base-10 TOML integers whose values are bytes; comments show the equivalent binary unit. URLs and paths are strings.
• Relative paths are rejected for state, socket, CA, shell-executable, and allowed-CWD-root fields. client.daemon_cwd is resolved once at startup and then stored and advertised as an absolute path. On Unix it is the omitted-CWD default; on Windows it is the protected parent under which the service creates an ACL-isolated default directory for the selected execution identity. The annotated client example uses Unix paths; a Windows deployment replaces state_dir, daemon_cwd, and relevant shell paths with absolute Windows paths. Shell fields for the other platform are syntax-checked but not resolved or advertised.
• The daemon prints its effective configuration after validation, with no command data or TLS material. Since v1 stores command/environment payloads in plaintext, configuration output is hygiene rather than a secrecy guarantee.

Limits and cross-field validation

Configuration may lower protocol and storage limits, but may not raise a hard wire ceiling above the v1 values in the examples. For every high/low watermark, 0 < low < high; send windows must fit below their corresponding durable quota. The 64 KiB command closeout reserve must fit within the command quota, and the command quota must fit within the client and server tiers. Queue and byte counts must be positive except where a comment explicitly gives zero a disabling or indefinite meaning. queue.max_per_client may not exceed queue.max_server.

The server must reject external JSON-RPC binds unless json_rpc.enabled=true. Any enabled non-loopback bind produces a conspicuous warning but is permitted by the accepted v1 debugging contract. The control Unix socket always uses mode 0600; it is not a configurable relaxation.

Windows automatic start is SCM state, not TOML state. Installation registers the machine-wide service as Automatic; an administrator may change it to Manual through the tray or normal service-management tools. RVBox has no windows.start_on_boot key and never attempts to reconcile two sources of truth. The optional per-user tray uses the installer-created logon registration and is never required for service readiness or command execution.

Shell executable resolution

Each ShellType maps to one startup-validated absolute executable path from [shells]. The client canonicalizes the path, verifies that it names an executable regular file appropriate to the platform, and advertises only shells that passed validation. The configured platform default must be one of those shells. There is no fallback.

The resolved executable is independent of a command's PATH override. For example, a request for SHELL_BASH still launches the validated /bin/bash even when the request contains PATH=/tmp/untrusted; it never searches that directory for another bash. An administrator may intentionally select another implementation, such as an absolute pwsh.exe path for SHELL_POWERSHELL, but the selection remains fixed until daemon restart.

Command text and uploaded scripts are written to generated wrapper paths and passed to exactly this executable. The user-supplied script filename is display metadata only.

Resource-profile composition

LIGHT is exclusive. Otherwise, a request may combine at most one CPU tier, one memory tier, and one disk tier. Thus CPU_HEAVY + MEM_MEDIUM is valid, while CPU_MEDIUM + CPU_HEAVY and LIGHT + MEM_HEAVY are invalid. A configured profile declares which controls are required. If the platform cannot apply a required control atomically before launch, the command is terminal REJECTED.

Profile names describe administrator-defined allowance classes: a HEAVY tier normally permits more resources than MEDIUM; RVBox does not invent numeric values. Zero for an individual numeric limit means that control is not requested by that profile, but every name in required_controls must have a nonzero, platform-applicable value. Linux disk limits use configured cgroup device major/minor keys. Windows applies the equivalent whole-Job rate control and ignores Linux device maps only when disk control is not declared required.

Validation ownership

internal/config owns TOML DTOs, strict decoding, default application, flag overrides, canonicalization, and cross-field validation. It converts the parsed form into immutable domain configuration before listeners or child processes start. Network, storage, and supervisor packages receive only their relevant validated sub-configuration and never parse TOML themselves.