88 lines
5.3 KiB
Markdown
88 lines
5.3 KiB
Markdown
---
|
|
name: rvbox
|
|
description: "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](references/deployment.md) 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](references/deployment.md): discover
|
|
paths and versions, choose a transport, configure/start clients, inspect health,
|
|
and preserve state during maintenance.
|
|
- [Commands and workflows](references/commands.md): every current CLI option,
|
|
retry-safe submission, scripts, stdin, profiles, signals, and client takeover.
|
|
- [History and Control API](references/control-api.md): command listings,
|
|
historical output, resumable follow, JSON-RPC, pagination, and structured errors.
|
|
- [Troubleshooting](references/troubleshooting.md): transport failures, queued
|
|
work, Windows identity/session/GUI issues, PowerShell policy, quotas, and recovery.
|
|
|
|
An optional Python 3 helper, [scripts/request_id.py](scripts/request_id.py),
|
|
prints a canonical UUIDv7 using only the standard library. It performs no RPC.
|
|
The bundled [Control schema](assets/control.protoset) supports clients such as
|
|
`grpcurl` without requiring server reflection or a repository checkout. Check
|
|
schema compatibility when operating a different RVBox version.
|