# RVBox v1 control plane

[`../protos/rvbox/v1/control.proto`](../protos/rvbox/v1/control.proto) defines
the canonical control API. `rvc` uses the `Control` gRPC service over the local
Unix-domain socket. The server also exposes the same unary operations through
an optional JSON-RPC 2.0 HTTP adapter for local debugging and batch automation.

## Endpoints

- Unix socket: enabled by default, mode `0600`, owned by the server account.
- HTTP JSON-RPC: disabled unless enabled; default bind `127.0.0.1:6900`.
  It has no authentication by design. Binding it beyond loopback is an explicit
  deployment choice and requires external protection.

gRPC can stream `RunCommandAndFollow` and `FollowCommand`. JSON-RPC remains
simple: callers issue work, query command state, poll event/output pages after
an event sequence, append stdin, close stdin, or signal a command. It does not
invent a separate event-stream protocol.

The JSON-RPC method names are the lower-camel protobuf operation names:
`listClients`, `getClient`, `listCommands`, `getCommand`, `runCommand`,
`appendStdin`, `closeStdin`, `signalCommand`, and `getOutput`. Parameters and
results use protobuf JSON mapping (including base64 strings for `bytes` and UTC
RFC 3339 strings for timestamps); JSON-RPC errors carry the corresponding
`ControlError` code/data. `getOutput` and `getCommand` are the polling path for
what gRPC exposes as follow streams.

## CLI semantics

`rvc stat` maps to `ListClients`, `GetClient`, `ListCommands`, and `GetCommand`.
History pages default to 20 commands and may request at most 100. Output pages
default to 100 lines; a line is a display operation over ordered chunks, not a
protocol boundary. Output can be filtered by stream and timestamped with the
server's recorded client-observed timestamp plus stream name.

`rvc run` creates a command. Foreground mode runs `RunCommandAndFollow`, which
streams output and stops on a terminal event. `--background` uses `RunCommand`
and returns the UUID immediately. Interrupting the CLI, timing out its local
wait, or losing the local control connection never cancels remote work. The
explicit `rvc kill` operation is the only termination path.

`rvc append` turns a string into `StdinWrite` with `append_newline=true` unless
the caller selects raw mode; `--file` supplies raw bytes; `--attach` streams
local standard input. `CloseStdin` is available separately. All stdin actions
are acknowledged and idempotent.

## Query behavior

Command details expose persisted request fields, effective execution metadata,
lifecycle, terminal result, output availability/truncation, current resource
snapshot, and `suspected_hung` diagnostics. The latter is informational and
must not be shown as a terminal state. Pagination response cursors are stable
within their declared ordering (newest issue time for command lists; increasing
`event_seq` for events/output).

The service returns `ControlError` codes for not found, offline, capacity,
invalid request, unsupported platform feature, conflict, truncation, and
internal/transient errors. It never encodes errors only as CLI text.