# RVBox v1 configuration contract

RVBox v1 uses TOML 1.0 for daemon configuration. The normative annotated
examples are [`examples/server.toml`](examples/server.toml) and
[`examples/client.toml`](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`](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.
- With an empty `tls.ca_file`, the client accepts a matching-host self-signed
  server leaf. This provides TLS encryption and hostname routing only; v1 makes
  no server-authentication or endpoint-ownership guarantee. Supplying a PEM CA
  bundle restores normal CA-chain verification and is the preferred future
  deployment model.

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