docs: add portable RVBox operations skill

This commit is contained in:
cabbage committed 2026-10-27 10:18:40 +00:00
1 parent 49bb103171
commit b52ca5a7c2
9 files changed
+646

No files matched your search

+2
View File
@@ -24,6 +24,8 @@ Read the documents in this order:
self-signed HTTPS browser gateway for the rare manual UAC recovery step. self-signed HTTPS browser gateway for the rare manual UAC recovery step.
10. [Linux-server operations runbook](operations-runbook.md) — deployment, 10. [Linux-server operations runbook](operations-runbook.md) — deployment,
backup/restore, upgrade, and incident response. backup/restore, upgrade, and incident response.
11. [Portable RVBox operations skill](../skills/rvbox/SKILL.md) — deployment
discovery, verified CLI syntax, Control API access, and troubleshooting.
The wire authority is in [`../protos/rvbox/v1`](../protos/rvbox/v1): The wire authority is in [`../protos/rvbox/v1`](../protos/rvbox/v1):
`common.proto` contains shared data types, `agent.proto` contains the `common.proto` contains shared data types, `agent.proto` contains the
+87
View File
@@ -0,0 +1,87 @@
---
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.
+4
View File
@@ -0,0 +1,4 @@
interface:
display_name: "RVBox Operations"
short_description: "Operate and troubleshoot RVBox with rvc"
default_prompt: "Use $rvbox to discover this deployment and carry out the requested RVBox operation, verifying its remote result."
Binary file not shown.
+145
View File
@@ -0,0 +1,145 @@
# Commands and workflows
## Contents
- Grammar and options
- Admission, completion, and retries
- Script and stdin workflow
- Signals, incidents, and client replacement
## Grammar and options
Use the `rv` prefix selected in [deployment.md](deployment.md). Keep command
options before CLIENT/UUID; for `storage` and `client`, put options before the
nested verb. Quote target command text as one argument. Global `--socket` and
`--request-id` are scanned across CLI arguments, so splitting target flags into
separate local arguments can accidentally make them control-CLI options.
| Command | Options / behavior |
| --- | --- |
| `stat [CLIENT [ISSUE_UUID]]` | No arguments lists clients; CLIENT inspects its connection/instance; UUID inspects that command. `--all` iterates client pages; `--per-page N` sets client page size, maximum 100. Does not list a client's commands. |
| `run CLIENT 'COMMAND'` | `--shell cmd\|powershell\|sh\|bash`; `pwsh` aliases the configured PowerShell executable, not a separate auto-discovered binary. `--background` returns after admission. |
| `run --script PATH CLIENT` | Uploads up to 10 MiB of script bytes with a computed SHA-256 descriptor. No COMMAND positional argument. Choose the shell explicitly. |
| Run settings | `--cwd ABS_TARGET_PATH`; repeat `--env KEY=VALUE`; repeat `--profile PROFILE`; `--elevated` requests Windows elevation; `--queue-ttl DURATION` controls queue acceptance expiry. |
| `append CLIENT ISSUE_UUID TEXT` | Adds one newline by default. `--raw` suppresses it. Supply TEXT even when empty; omission is not a valid input form. |
| `append --file PATH CLIENT ISSUE_UUID` | Reads file bytes; use `--raw` when no extra newline is wanted, including binary input. The file option alone does not disable the newline. |
| `close-stdin CLIENT ISSUE_UUID` | Durable ordered EOF; no later writes. |
| `kill [SIGNAL] CLIENT ISSUE_UUID` | Defaults to TERM. Use uppercase TERM/SIGTERM or KILL/SIGKILL for Windows. Parser also recognizes HUP, INT, USR1, USR2, but Windows rejects them. |
| `storage incidents` | Unresolved incidents; `storage --all incidents` includes resolved records. Current CLI does not iterate incident pages; use the API for a complete paginated list. |
| `storage repair INCIDENT_ID` | Requests resolution of an automatically repairable incident without known data loss. Do not assume the current implementation performs a general filesystem repair. |
| `storage acknowledge INCIDENT_ID 'NOTE'` | Accepts the incident's documented loss; note is a positional argument, maximum 4 KiB. There is no `--note` flag. |
| `client takeover CLIENT INSTANCE_UUID` | Authorizes the exact pending instance's next matching connection. Does not reset the client or erase history. |
All mutations accept the optional global `--request-id UUIDv7`. Otherwise `rvc`
generates an ID. UUIDs must be canonical lowercase UUIDv7, not UUIDv4 or a
JSON-RPC envelope ID. Reads ignore this option. For `run` it becomes the
`issue_uuid`; other actions have their own request ID plus a target issue or
incident UUID. Use a new ID for a new action, including consecutive stdin writes.
Profiles are `light`, `cpu-medium`, `cpu-heavy`, `mem-medium`, `mem-heavy`,
`disk-medium`, and `disk-heavy`. `light` is exclusive; otherwise combine at most
one tier per resource. Values come from administrator policy, not from the
names. Required controls that cannot be applied cause pre-launch rejection.
Neither a resource profile nor `--elevated` changes the selected shell.
`--queue-ttl` omission uses the server default, normally 15 minutes; `0` means
no queue expiry. It is not a runtime timeout. Expiry can precede a late client
report; inspect `queue_expired` / `late_after_expiry` and the actual lifecycle.
## Admission, completion, and retries
`run` prints ISSUE_UUID and admission lifecycle. Foreground then follows durable
history, rendering output and lifecycle only, for at most the CLI's remaining
30-second context. `--background` does not wait for client acceptance, launch,
or completion. A completed RPC/follow can return CLI exit `0` while the remote
command is FAILED, REJECTED, or another terminal state.
After dispatch, use `stat CLIENT ISSUE_UUID` and, when needed, the
[Control API](control-api.md). Terminal states are SUCCEEDED, FAILED,
TERMINATED, CANCELLED, INTERRUPTED, EXPIRED, and REJECTED. QUEUED, DISPATCHED,
ACCEPTED, and RUNNING are not terminal. FAILED means execution launched;
REJECTED means validation/context/launch prerequisites failed. Preserve output
loss flags separately from the process result.
For a transient transport failure, inspect first and retry with bounded backoff
using **the same request ID and exact payload**. Changing command, shell, CWD,
env, script bytes, profile, elevation, TTL, method, or target can conflict.
The current CLI does not implement an automatic retry loop. Stop on a payload
conflict, permanent validation error, or missing evidence after the retry budget;
do not manufacture a fresh ID to make an uncertain side effect run again.
Deduplication relies on retained state; reset/lost storage and reclaimed history
are not an unlimited exactly-once guarantee for application side effects.
### Example 1: submission that survives an uncertain response
Set CLIENT, SKILL_DIR, and an owned persistent RUN_DIR on the controller.
Create the ID **once**, before submitting:
```sh
mkdir -p "$RUN_DIR"
python3 "$SKILL_DIR/scripts/request_id.py" > "$RUN_DIR/inspect.request-id"
```
On the first attempt or a retry, read the recorded value and keep the request
unchanged:
```sh
REQUEST_ID=$(cat "$RUN_DIR/inspect.request-id")
rv --request-id "$REQUEST_ID" run --background --shell cmd \
--queue-ttl 15m "$CLIENT" 'whoami & echo %USERPROFILE%'
rv stat "$CLIENT" "$REQUEST_ID"
```
Do not rerun the ID-generation step for that operation. A follow timeout does
not justify a new submission. Use the API to recover historical output or resume
events; `stat` alone does not print the command's stdout.
## Script and stdin workflow
An explicit `--cwd` is a directory on the target, not the controller. On Windows,
an omitted CWD is identity-scoped service work space, not the active user's home.
Config paths do not expand `%ProgramData%` automatically; shell command text does
expand the target shell's own variables. Wrappers are not interactive terminals:
no PTY, TTY job control, desktop input, or implicit local stdin forwarding.
### Example 2: ordered input and EOF
For a Windows client, `findstr` provides a small stream consumer that stays open
until EOF. Generate and retain three distinct IDs before attempting the actions:
```sh
ISSUE=$(python3 "$SKILL_DIR/scripts/request_id.py")
WRITE_ID=$(python3 "$SKILL_DIR/scripts/request_id.py")
EOF_ID=$(python3 "$SKILL_DIR/scripts/request_id.py")
rv --request-id "$ISSUE" run --background --shell cmd "$CLIENT" '@findstr /n "^"'
rv --request-id "$WRITE_ID" append "$CLIENT" "$ISSUE" 'hello'
rv --request-id "$EOF_ID" close-stdin "$CLIENT" "$ISSUE"
rv stat "$CLIENT" "$ISSUE"
```
Retain these IDs if a response is lost. Input can be queued before launch, but
the returned write sequence proves durable intent, not that the program consumed
the bytes. Use stdin acknowledgement events and historical output to confirm.
Do not send EOF until all intended writes are admitted; it permanently closes
that command's stdin. For binary data use `append --raw --file`, and split
large input into bounded writes (configured raw chunk limit, normally 64 KiB).
## Signals, incidents, and client replacement
TERM requests graceful shutdown; Windows sends a best-effort console CTRL_BREAK
and escalates to Job termination after the grace period (normally 10 seconds).
KILL terminates the whole Job immediately. The returned revision is server
admission, not proof of delivery: inspect signal-result events and terminal
lifecycle. Neither operation reverses the program's prior side effects.
For incidents: list and inspect first, preserve evidence, use repair only for
the safe repairable case, and acknowledge only when acceptance of the documented
loss is authorized. Resolution records remain in history; it is not a purge.
Do not use acknowledgement merely to turn a readiness indicator green.
For replacement: `stat CLIENT` exposes active and pending instance UUIDs.
Confirm the intended replacement before `client takeover`; the default grant
is one-shot and expires in five minutes. The matching reconnect consumes it and
fences the old session. When the old session is no longer live, normal replacement
does not require this grant. Do not confuse instance UUID, command UUID, and
request ID or clone a client's live state directory to obtain a second identity.
+130
View File
@@ -0,0 +1,130 @@
# History and Control API
## Contents
- Access without server reflection
- Method reference
- Pagination, streaming, and bytes
- Optional JSON-RPC
## Access without server reflection
Use this for command listings, historical output, event resumption, full client
capabilities, and acknowledgement/resource/signal events that `rvc` does not
render. The canonical service is `rvbox.v1.Control` on the same local Unix socket.
The reviewed server does not register gRPC reflection.
Use an available generated client, or `grpcurl` with the bundled
`assets/control.protoset`. Run where the socket is accessible under its owner;
the schema and tool must be present in that environment too. `SKILL_DIR` below
means the skill's actual installation path, not a required global location.
```sh
grpcurl -plaintext -unix \
-protoset "$SKILL_DIR/assets/control.protoset" \
-d '{"clientId":"CLIENT","includeTerminal":true,"pageSize":20}' \
"$CONTROL_SOCKET" rvbox.v1.Control/ListCommands
```
Replace CLIENT and other example tokens with actual values. `-plaintext` here
selects local gRPC without TLS; it does not change the WSS connection's TLS.
If `grpcurl` is absent, use existing approved tooling rather than assuming it is
bundled with RVBox. With a matching source checkout, `-import-path PROTOS_DIR
-proto rvbox/v1/control.proto` is another schema source. See the
[grpcurl reference](https://github.com/fullstorydev/grpcurl) for its own flags.
The descriptor contains imports and all Control methods. Regenerate it after a
protocol change using `buf build --as-file-descriptor-set --path
protos/rvbox/v1/control.proto -o skills/rvbox/assets/control.protoset` in the
matching repository/toolchain. A bundled schema is a versioned snapshot, not
proof that an older/newer server implements a method.
## Method reference
Names below are gRPC methods. JSON-RPC uses the same name with its first letter
lowercase. Parameter names use protobuf JSON spelling.
| Method | Main request fields / result |
| --- | --- |
| `ListClients` | `pageSize`, `pageToken` → `clients`, `nextPageToken` |
| `GetClient` | `clientId` → client identity, connection, `supportedShells`, `daemonCwd`, platform/version/architecture, pending replacement |
| `ListCommands` | `clientId`, `includeTerminal`, `pageSize`, `pageToken` → `commands`, `nextPageToken` |
| `GetCommand` | `clientId`, `issueUuid` → command record plus latest resource snapshot |
| `RunCommand` | `targetClientId`, `spec`, optional `scriptContent`, `requestId`, `queueTtl` → `issueUuid`, lifecycle |
| `FollowCommand` | `clientId`, `issueUuid`, `includeExisting`, `afterEventSeq` → server stream; **gRPC only** |
| `AppendStdin` | `clientId`, `issueUuid`, bytes `data`, `appendNewline`, `requestId` → `writeSeq` |
| `CloseStdin` | `clientId`, `issueUuid`, `requestId` → `writeSeq` |
| `SignalCommand` | `clientId`, `issueUuid`, `signal`, `requestId` → `commandRevision` |
| `GetOutput` | `clientId`, `issueUuid`, optional `streams`, `afterEventSeq`, `maxBytes`, `pageToken` → output slices, loss metadata, `nextPageToken` |
| `ListStorageIncidents` | `includeResolved`, `pageSize`, `pageToken` → incidents, `nextPageToken` |
| `RepairStorageIncident` | `incidentId`, `requestId` → resolved incident |
| `AcknowledgeStorageIncident` | `incidentId`, `note`, `requestId` → acknowledged incident |
| `AuthorizeClientTakeover` | `clientId`, `clientInstanceId`, `requestId` → `expiresAt` |
`spec` selects one of `commandText` or `script`, plus `shellType`, `cwd`,
`envOverrides`, `executionProfiles`, and `elevated`. Shell enum names are
`SHELL_CMD`, `SHELL_POWERSHELL`, `SHELL_SH`, and `SHELL_BASH`. For scripts,
`script` holds `filename`, `sizeBytes`, and bytes `sha256`; `scriptContent`
must match the size and digest. Prefer `rvc --script` to construct this correctly.
## Pagination, streaming, and bytes
- JSON bytes are **base64**, not literal output text. This includes output
slice `data`, stdin `data`, script bytes, and digests. Protobuf 64-bit numbers
commonly appear as JSON strings. Durations use forms such as `"900s"`, not
CLI duration syntax `15m`; timestamps use RFC 3339.
- List APIs return bounded pages (default 20, maximum 100). Iterate
`nextPageToken` until empty; preserve the exact filters. `rvc stat --all`
handles client pages only. The incidents CLI currently shows just one page.
- `GetOutput` pages by bytes and can split an event. Default `maxBytes` is
1 MiB, maximum 16 MiB. Reuse its opaque token with unchanged client, issue,
and stream filters; preserve `(eventSeq, eventByteOffset, endOfEvent)` when
assembling slices. Do not assume line boundaries or advance past a partially
read event. A token's snapshot does not include subsequently appended events.
If a token becomes invalid after a server restart or retention change, restart
the read from a known boundary and deduplicate slices; do not resubmit work.
- For live output, finish the current snapshot before polling a new one, or
resume `FollowCommand` after the last fully handled event sequence. First
historical follow uses `includeExisting:true`; an empty cursor with false
intentionally starts after the current history. Cursor filters and stream
enums (`STREAM_STDOUT`, `STREAM_STDERR`) must remain consistent.
- Keep `outputTruncated`, `truncations`, and `incomplete` metadata when present.
A command can succeed with missing output. A server retention marker is not
a client event and must not advance `afterEventSeq`. Do not infer complete
history from CLI-rendered text alone.
## Optional JSON-RPC
Use an already-enabled or explicitly requested debug endpoint. It is disabled
by default, unauthenticated in v1, and independent of public `/v1/agent`.
Discover its actual listener/proxy path; the default bind is loopback port 6900.
The built-in handler accepts POST at its listener; a deployment proxy can choose
a path. Keep the deployment's intended exposure rather than changing it just
to make a query convenient.
An output request body can be sent using existing HTTP tooling:
```json
{
"jsonrpc": "2.0",
"id": "output-page-1",
"method": "getOutput",
"params": {
"clientId": "CLIENT",
"issueUuid": "ISSUE_UUID",
"maxBytes": "65536"
}
}
```
Send it with `Content-Type: application/json`, inspect `error` even on HTTP
200, decode output `data` from base64, and continue `result.nextPageToken`.
Every request needs a non-null `id`; batches and notifications are not supported
by this adapter. That envelope `id` only correlates responses. Mutation
deduplication uses `params.requestId`; if omitted the server generates one,
which is convenient but prevents reliable retry after an uncertain response.
Unknown parameters are rejected. Inspect transport status and structured
`ControlError` (`code`, `message`, `retryable`, and `issueUuid`) when provided;
not every transport error has RVBox details. Consult
[troubleshooting](troubleshooting.md) before retrying a mutation.
+134
View File
@@ -0,0 +1,134 @@
# Deployment and service operations
## Contents
- Discover the layout
- Select a control transport
- Configure and operate daemons
- Maintain persistent state
## Discover the layout
Record the server host/cluster, project and service/container identity, binary
version, explicit TOML path, control socket, process UID, persistent state, WSS
endpoint, and configured diagnostics. Use the deployment's manifests, process
arguments, service records, and existing inventory. Do not assume a fixed
Compose directory, image path, service manager, port, or server account.
`rvc` is the Linux control client. It connects to the server's local Unix gRPC
socket, not to a Windows named pipe, public HTTPS URL, or JSON-RPC HTTP address.
A socket inside a container does not automatically exist on its host. Prefer
running `rvc` inside the server container as its configured user rather than
changing the socket's `0600` permissions. A Windows operator can use an existing
Linux controller, SSH route, or suitable container environment.
`rvc --version` prints the client version. Current `rvc --help` is not a
complete command reference. If source is available, use `cmd/rvc/main.go`,
`cmd/rvbox/main.go`, `cmd/rvbox-server/main.go`, and
`protos/rvbox/v1/control.proto`; design documents can describe unfinished CLI
features. No separate `rvc output`, `follow`, `attach`, or history-list verb is
implemented in the reviewed build.
## Select a control transport
Set the variables for the chosen layout. Define **one** POSIX-shell function
called `rv`; references use it only as a prefix, not as an installed command.
| Layout | Prefix definition |
| --- | --- |
| Direct access to socket | `rv() { "$RVC_BIN" --socket "$CONTROL_SOCKET" "$@"; }` |
| Existing Compose stack | `rv() { docker compose -f "$COMPOSE_FILE" -p "$PROJECT" exec -T "$SERVICE" "$RVC_BIN" --socket "$CONTROL_SOCKET" "$@"; }` |
| Known container | `rv() { docker exec -i "$CONTAINER" "$RVC_BIN" --socket "$CONTROL_SOCKET" "$@"; }` |
| Kubernetes pod/container | `rv() { kubectl -n "$NAMESPACE" exec -i "$POD" -c "$CONTAINER" -- "$RVC_BIN" --socket "$CONTROL_SOCKET" "$@"; }` |
Here `RVC_BIN` is the binary path **inside that execution environment**. Inspect
the actual image: installed and test images may use different paths. Include all
required Compose files/overrides and the existing project name. Do not allocate
a TTY when uploading scripts or collecting bytes. `exec -i` preserves stdin;
it does not attach the local terminal to the remote command's stdin.
For SSH, perform the same operation on the server/controller host. SSH normally
joins command arguments into a remote shell string; passing `"$@"` to `ssh`
alone does not preserve argument boundaries. Use a quoted remote script or
proper POSIX argument escaping. For a one-off read:
```sh
ssh "$SERVER_HOST" 'sh -s' <<'REMOTE'
/absolute/path/rvc --socket /absolute/path/server.sock stat --all
REMOTE
```
Replace the example's paths on that host. Remote variables in a quoted
here-document expand remotely. Preserve host verification. Distinguish local
sandbox denial from proxy, DNS, authentication, and host-key errors; use the
established authorized access route before declaring the host unavailable.
Files passed to `--script` or `append --file` are read where `rvc` runs. Copy or
mount them there, or use `/dev/stdin` with stdin forwarding on Linux. For example,
`rv run --shell cmd --script /dev/stdin CLIENT < local-script.cmd` uploads local
bytes through an stdin-capable prefix. Script filename is display metadata;
the explicit shell determines execution. Appending `--raw --file /dev/stdin`
similarly supplies exact input bytes. This CLI has no `--attach` mode.
## Configure and operate daemons
| Component | Supported operator action |
| --- | --- |
| Linux server | `rvbox-server --version`; `rvbox-server --config ABS_PATH --check-config`; normal entrypoint `rvbox-server --config ABS_PATH` |
| Windows client | `rvbox.exe --version`; `rvbox.exe --check-config --config ABS_PATH` |
| Windows installation | Double-click a packaged executable for UAC installation; it starts SCM service and current-user tray. Programmatic installation uses `--install-service --config ABS_PATH` against a deliberately placed executable. |
| Windows service | `rvbox.exe --start-service`, `--stop-service`, `--restart-service`, `--uninstall-service`, or `--configure-service --startup automatic|manual`; administrative rights required. |
| Windows tray | `rvbox.exe --tray --config ABS_PATH` on the user's desktop; Exit affects only the tray. SCM remains responsible for the service. |
Find the installed Windows binary and explicit config from SCM, e.g.
`sc.exe qc RVBoxClient`, rather than assuming the installer defaults. Defaults
usually place the binary under Program Files and config under
`%ProgramData%\RVBox\client.toml`. Installation preserves existing TOML. Its
packaged bootstrap URL is only a first-install default. `--service` is an SCM
entrypoint; `--launcher`, `--signal-helper`, and installer-internal options are
not operator APIs. Release builds reject test fault-injection flags.
The Windows GUI executable may require `Start-Process -Wait -PassThru` when a
local automation runner needs a reliable process completion/exit code. Verify
SCM state and logs as well; a management wrapper returning does not prove readiness.
Stopping or restarting the Windows service terminates its supervised Jobs;
inspect affected work before an authorized service lifecycle change.
Configuration is UTF-8 TOML with strict keys/types. Use the actual build's
annotated examples when available. Operational groups include routing/identity,
state and work paths, shell executables, TLS, queues/TTL, storage/retention,
resource profiles, and optional observability. Byte limits use integers and
durations use quoted Go durations. RVBox does not implicitly load daemon config
from environment variables; deployment-script environment variables are separate.
There is no TOML hot reload: validate and restart the affected daemon through
its existing deployment. Windows Automatic/Manual startup belongs to SCM.
Shells resolve to validated absolute executable paths at startup. A command's
`PATH` override changes child lookup, not RVBox's shell executable selection.
With an empty client `tls.ca_file`, v1 accepts matching-host self-signed server
certificates; it does not authenticate endpoint ownership. An explicit CA bundle
enables normal chain verification. Diagnose hostname/path/time/CA settings
without assuming any arbitrary certificate is valid.
Observability may be disabled or fail to bind without preventing startup. When
enabled, inspect configured liveness/readiness/metrics paths (normally
`/livez`, `/readyz`, `/metrics`). Liveness is not readiness. Server recovery is
asynchronous; client readiness additionally needs a reconciled WSS session.
Readiness HTTP absence alone is not evidence that the daemon is stopped.
## Maintain persistent state
Use the existing Compose or other deployment lifecycle; do not introduce a new
service manager as part of operating an existing server. Before an authorized
backup/upgrade/restore, record versions and status, stop the server gracefully,
and back up its **entire** configured data tree, including SQLite/WAL and
segments. Keep Windows client spool and identity separate from server storage.
Restore matching binary/config/data with their intended ownership, validate,
restart, and verify recovery plus a known client's connection. Preserve the
failed copy for diagnosis. Do not edit SQLite or delete live segments to fix
health. Internal data is plaintext in v1, including command/env/stdin payloads.
Use online storage incident operations where supported. The reviewed binaries
do not implement the offline `rvbox repair` / `rvbox-server repair` modes
described in some design documents. Check the deployed version before using
an operation beyond the verified interface.
+120
View File
@@ -0,0 +1,120 @@
# Troubleshooting
## Contents
- Triage by symptom
- Windows identity, GUI, and shells
- Storage, output loss, and recovery
## Triage by symptom
Record the deployment route, versions, client ID, issue/request IDs, exact
arguments, timestamps, status/event details, and relevant daemon logs. Keep the
initial evidence; do not restart services or resubmit work merely to inspect it.
| Symptom | Check / next action |
| --- | --- |
| Local sandbox denies Docker/SSH | Use the established authorized execution route. This does not establish a remote outage. Preserve SSH host verification. |
| Socket missing / connection refused | Confirm namespace, server process, explicit socket config, container mounts, and startup logs. A running proxy alone does not prove the server is listening. |
| Socket permission denied | Run as the existing socket owner through the deployment route; inspect directory traversal and mount permissions. Do not chmod the control socket world-accessible. |
| Client missing or NOT_FOUND | List all client pages; verify the exact registered ID and server instance. A hostname assumption or wrong Compose project can select different state. Retention can also remove command history. |
| Disconnected / OFFLINE / UNAVAILABLE | Separate server recovery from client connectivity. Inspect SCM, WSS hostname/path, proxy WebSocket upgrade, certificate/time/CA, DNS, reconnect logs, and pending instance conflicts. Missing optional HTTP health is not proof of a stopped daemon. |
| QUEUED persists | Check connection, supported shell, queue/running capacity, acceptance events, and queue expiry. Queuing does not promise execution, and queue TTL is not a runtime timeout. |
| CLI deadline / broken stream | Work may still run. Query the captured issue and resume history via the API. For uncertain admission, retry only with the same request ID and payload. |
| CLI exit 0 but task failed | Inspect remote terminal lifecycle, rejection/detail, and output. A successful follow stream is not a successful process. |
| INVALID_ARGUMENT / unsupported shell | Verify argument order, UUIDv7 format, profile composition, explicit shell and advertised support, target CWD, and upload size/hash. Current CLI discards an unknown `--shell` parse error and can fall back to the server default; use only verified names. |
| CONFLICT / AlreadyExists | Same ID with changed content/target, or a client-instance conflict. Stop retrying unchanged assumptions; inspect the original command or pending claimant. Do not assign a new ID to duplicate an uncertain side effect. |
| CODE_ALREADY_EXECUTED / reclaimed history | Inspect remaining execution/tombstone evidence. Missing full output does not establish that the operation never ran; require a deliberate new operation before resubmission. |
| PROTOCOL_ERROR / incompatible peers | Compare versions and negotiated capabilities, then inspect bounded server/client logs. Preserve IDs and durable records rather than rewriting event sequences or instance state. |
| REJECTED / context or elevation unavailable | Code did not launch. Inspect attempted/effective context and rejection. Fix prerequisites; a new intentional execution needs a new command request ID. |
| Stdin accepted but no response | Check `writeSeq`, stdin acknowledgement, consumer buffering, newline mode, queue state, EOF, and whether the command is already terminal. There is no PTY. |
| Signal admitted but process remains | Inspect signal-result events and whole-Job lifecycle. TERM can be ignored and escalated; API acknowledgement is not signal delivery or completed termination. |
| CAPACITY_EXHAUSTED / ResourceExhausted | Identify command/client/server quota versus actual filesystem free space. Lower payload/queue pressure, wait for eligible retention, or adjust authorized capacity; repeated retries without a change will not help. |
| Dirty readiness / output incomplete | List incidents, isolate the affected scope, preserve evidence, and use the recovery procedure below. A process can remain live while one scope is unhealthy. |
Treat `retryable` as permission to consider a bounded retry, not proof that
immediate repeated calls will succeed. Do not parse error text into invented
stable exit-code classes: the current CLI normally exits 1 for its own errors
and exposes remote lifecycle separately.
## Windows identity, GUI, and shells
`--elevated` is the only execution-context request toggle. Selection and
fallback happen in the Windows client before launch, never by retrying user
code after it starts:
| Usable active session | Normal request | Elevated request |
| --- | --- | --- |
| Exactly one | active-user | active-user-elevated → active-system → local-system |
| None, or ambiguous multiple candidates | local-service | local-system |
Read `windows_requested_elevated`, attempted/effective contexts, effective SID,
session ID/user SID, and selection detail from command status. `active-system`
is SYSTEM in the active session, not the user's elevated profile. SYSTEM in
Session 0 cannot substitute for an interactive desktop. Fallback completes
before authorization; a later command failure does not trigger another role.
GUI, audio, display, and per-user shell operations need the intended interactive
session and desktop. NTFS ACLs, HKCU/profile, mapped drives, and network identity
follow the effective token. A single-owner laptop may have a split admin token,
but do not assume it. If a UI does not appear, verify both token/session and
window station/desktop; a process listing alone is insufficient.
### Opening folders and Explorer exit code 1
For shell folder opening, use `start "" "%USERPROFILE%"` through `--shell cmd`.
The first quoted argument is the empty window title. This was verified to open
the active user's home and return 0. Direct `explorer.exe PATH` was observed
returning 1 while another Explorer process displayed the requested folder.
That raw exit code remains a failed command; do not globally reinterpret 1 as
success or assume it always proves a successful handoff. For GUI tasks, inspect
the actual window/effect as well. `start` reports launch, not later application
success. A window delegated to another process does not share the launcher's
lifetime; killing the completed launch command is not a way to close that
window. See [Microsoft's start documentation](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/start).
### PowerShell policy and encoding
The reviewed PowerShell wrapper uses `-NoLogo -NoProfile -NonInteractive -File`;
it does not bypass script policy. A Windows baseline with Restricted policy can
therefore reject `--shell powershell` before user code executes. `pwsh` selects
the same configured shell path; it is not a workaround. Check the configured
executable and effective execution policies. For a compatible task, use cmd or
an explicit PowerShell `-Command` invocation; do not silently relax machine or
Group Policy settings. A process-scoped policy exception is a deliberate
deployment choice, not a change this skill makes automatically.
Use uploaded scripts to avoid layers of quoting. Current Windows wrappers use
UTF-8 for cmd and UTF-8 with BOM for PowerShell; cmd's execution/output still
depends on its code page. Upload alone does not fix Unicode interpretation.
Do not assume Linux quoting or console encoding
transfers unchanged. Inspect raw API bytes when text rendering looks corrupt.
## Storage, output loss, and recovery
The per-command budget includes compressed command-owned data, not only stdout:
scripts, stdin, metadata, events, and retained output also consume it. Separate
limits apply per command, per client, and to the server, plus physical free-space
floors. Active and otherwise essential state cannot simply be evicted. Eligible
terminal commands and their owned data rotate by quota/age; default terminal
retention is 30 days. Audit/resolved incident history has a separate budget,
normally 100 MiB. Read actual config before treating any default as current.
For a dirty scope:
1. Inspect `rv storage incidents` and full API incident data, including scope,
data-loss flag, and automatically-repairable flag. Page through all records.
2. Preserve logs and a consistent copy before an authorized repair or loss
acceptance. Healthy scopes can remain usable during scoped recovery.
3. Request `storage repair` only for a safe repairable case. Current online
resolution is not a general-purpose reconstruction tool. When the loss is
understood and authorized, `storage acknowledge INCIDENT_ID 'NOTE'` records
acceptance; it does not recover lost bytes or erase incident history.
4. Recheck incident state, readiness, and the affected command/output. For an
unrepairable or inaccessible store, use the deployment's backup/restore path;
do not invent unavailable offline repair flags.
Output truncation/incompleteness and command lifecycle are separate facts.
Retention and late client reconciliation can change what evidence remains.
Never clear live databases, WALs, client instance state, or segments to suppress
an error, make an ID reusable, or pretend a command did not execute.
+24
View File
@@ -0,0 +1,24 @@
#!/usr/bin/env python3
"""Print one canonical UUIDv7; no third-party dependencies or network access."""
import secrets
import time
import uuid
def new_request_id():
milliseconds = time.time_ns() // 1_000_000
if not 0 <= milliseconds < 1 << 48:
raise ValueError("current timestamp does not fit UUIDv7")
value = (
(milliseconds << 80)
| (7 << 76)
| (secrets.randbits(12) << 64)
| (2 << 62)
| secrets.randbits(62)
)
return str(uuid.UUID(int=value))
if __name__ == "__main__":
print(new_request_id())