3.0 KiB
RVBox v1 control plane
../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.