5.3 KiB
name, description
| name | description |
|---|---|
| rvbox | Operate and troubleshoot RVBox deployments through rvc and the Control API: run remote commands or scripts, inspect results and output, manage stdin and signals, diagnose Windows execution, and handle service or storage incidents. Use for RVBox operations across local, SSH, container, and orchestrated deployments. |
RVBox operations
Use the deployment already present. Discover its addresses, paths, accounts, versions, and supported capabilities; never substitute a remembered test host, container name, credential, client ID, or filesystem layout. This reference matches RVBox v1 source reviewed on 2026-10-27: Linux server and Windows client. Unix-like client implementation is outside that release.
Establish the control route
Identify the intended server, its rvc binary, absolute control-socket path,
and socket-owning account. The default socket is /run/rvbox/server.sock, mode
0600. Paths belong to the namespace where rvc runs. The client's WSS URL is
not an rvc endpoint. See deployment access for
local, Compose, container, Kubernetes, and SSH layouts.
Choose one rv function from that reference as the deployment-specific prefix.
Then run rv stat --all, select the exact returned client ID, and inspect
rv stat CLIENT before dispatch. Use rvc --version separately to identify
the binary; version/help behavior is not a substitute for feature discovery.
Quick reference
Flags precede positional arguments, including the verbs after storage and
client. Uppercase tokens below are values to replace.
| Task | Command after choosing the rv prefix |
|---|---|
| List every client | rv stat --all |
| Inspect a client / command | rv stat CLIENT / rv stat CLIENT ISSUE_UUID |
| Run Windows command; follow output | rv run --shell cmd CLIENT 'whoami' |
| Admit work without following | rv run --background --shell cmd CLIENT 'COMMAND' |
| Upload a script | rv run --shell cmd --script PATH CLIENT |
| Supply execution settings | rv run --shell cmd --cwd 'C:\PATH' --env KEY=VALUE CLIENT 'COMMAND' |
| Send a line / exact file bytes | rv append CLIENT ISSUE_UUID 'TEXT' / rv append --raw --file PATH CLIENT ISSUE_UUID |
| Send EOF | rv close-stdin CLIENT ISSUE_UUID |
| Request graceful / forced termination | rv kill TERM CLIENT ISSUE_UUID / rv kill KILL CLIENT ISSUE_UUID |
| List unresolved / all incidents | rv storage incidents / rv storage --all incidents |
| Resolve an incident | rv storage repair INCIDENT_ID or rv storage acknowledge INCIDENT_ID 'NOTE' |
| Authorize a pending replacement | rv client takeover CLIENT PENDING_INSTANCE_UUID |
Rules that prevent wrong results
- Verify the remote result. CLI exit
0means the CLI completed its RPC or follow stream; it does not implyCOMMAND_SUCCEEDED. Capture the issue UUID, terminal lifecycle, rejection/detail, and relevant output. Foreground output mixes stdout/stderr and lifecycle messages; it is not a clean data stream. - Separate admission from execution. Background admission, stdin sequence, signal revision, and takeover expiry acknowledge server-side operations, not their eventual effects. Inspect status/events or the actual requested result.
- Preserve identity on retries. For an uncertain mutation, reuse its exact
UUIDv7
--request-idand unchanged payload. Forrun, that ID is also the issue UUID; subsequent stdin/signal actions each need their own request ID. Reads ignore the option. Do not retry an uncertain side effect with a new ID. - A lost observer does not stop work. Current CLI calls, including a foreground follow, have a 30-second context. Timeout, Ctrl+C, or lost SSH does not cancel the remote command. Query the known issue before proceeding.
- Select the shell explicitly. For Windows, start with
--shell cmdunless PowerShell execution has been verified. Shell omission currently selects PowerShell on the server. Quote target command text as one argument so local shell expansion cannot change%USERPROFILE%,$env:..., or redirections. - Respect scope. A skill grants no extra authority to change deployments, elevate commands, replace clients, acknowledge data loss, or delete state. Use existing authorization; do not add a confirmation step when already covered.
Read only the relevant detail
- Deployment and service operations: discover paths and versions, choose a transport, configure/start clients, inspect health, and preserve state during maintenance.
- Commands and workflows: every current CLI option, retry-safe submission, scripts, stdin, profiles, signals, and client takeover.
- History and Control API: command listings, historical output, resumable follow, JSON-RPC, pagination, and structured errors.
- Troubleshooting: transport failures, queued work, Windows identity/session/GUI issues, PowerShell policy, quotas, and recovery.
An optional Python 3 helper, scripts/request_id.py,
prints a canonical UUIDv7 using only the standard library. It performs no RPC.
The bundled Control schema supports clients such as
grpcurl without requiring server reflection or a repository checkout. Check
schema compatibility when operating a different RVBox version.