Files
rvbox/skills/rvbox/SKILL.md
T

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 0 means the CLI completed its RPC or follow stream; it does not imply COMMAND_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-id and unchanged payload. For run, 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 cmd unless 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.