# RVBox v1 design set

This design set turns the initial proposal into an implementation contract.
Read the documents in this order:

1. [Architecture](architecture.md) — scope, trust model, state machine,
   execution, storage, and retention decisions.
2. [Agent protocol](protocol.md) — WSS framing, sessions, replay, ordering,
   script transfer, heartbeat, and failure containment.
3. [Control plane](control-plane.md) — `rvc`, Unix-socket gRPC, JSON-RPC, and
   query/foreground semantics.
4. [Platform and operations](platform-and-operations.md) — Windows contract,
   recovery, storage safety, telemetry, and defaults.
5. [Configuration contract](configuration.md) — strict TOML loading, shell
   resolution, cross-field validation, and annotated server/client examples.
6. [Go implementation plan](implementation-plan.v1.md) — phased build order,
   package boundaries, storage/session/client details, tests, and release gates.
7. [Implementation testing](testing.md) — container entry points, run
   lifecycle, exact cleanup, and coverage inventory.
8. [Provisioned Windows test VM](testing-vm.md) — exact fixture identity,
   host/guest access, endpoints, snapshots, credentials contract, reset
   procedure, and known limitations.
9. [Interactive VM access](../test/rdp-access/README.md) — temporary,
   self-signed HTTPS browser gateway for the rare manual UAC recovery step.
10. [Linux-server operations runbook](operations-runbook.md) — deployment,
    backup/restore, upgrade, and incident response.

The wire authority is in [`../protos/rvbox/v1`](../protos/rvbox/v1):
`common.proto` contains shared data types, `agent.proto` contains the
client/server WebSocket envelopes, and `control.proto` defines the local gRPC
service that the HTTP JSON-RPC adapter mirrors.