@bekirdag/cvbox

CVBox

@bekirdag/cvbox is the secure, outbound-only machine agent for Clone Version. It lets an invited Clone Version owner inspect the full filesystem visible to the unprivileged CVBox service account, safely edit existing files after an explicit interactive unlock, view repository status and machine health, inspect a redacted process inventory, and run explicitly unlocked terminal sessions without exposing an inbound port or SSH credentials. When the server qualification flag is enabled, CVBox can also open a bounded outbound-only Remote Desktop session that starts view-only and requires a separate approval before keyboard or pointer input. Sensitive paths remain denied by file APIs; a terminal has the normal authority of the CVBox service account and must be treated as full user-level machine access.

Requirements

• Node.js 22 or newer
• macOS or Linux for automatic background-service installation
• HTTPS Clone Version endpoint, except for loopback development
• A one-time pairing code created in More → Machines

Install and enroll

npm install --global @bekirdag/cvbox
cvbox enroll --server https://app.cloneversion.com

Copy the pairing code from the Machines page, paste it into the hidden prompt, then press Enter. Bullets confirm that input was received without echoing the secret. Never put the code in a shell argument. CVBox creates an Ed25519 device key in ~/.cvbox/state.json, locks the directory to mode 0700 and the state file to 0600, then waits for fingerprint confirmation in Clone Version.

Fresh enrollment defaults to full-computer scope (/ on macOS/Linux and every available drive root on Windows). Use one or more --root /absolute/path options only when intentionally restricting the machine to selected folders. Existing machines can migrate with cvbox roots full; Clone Version will show the expanded scope for owner approval after the next signed heartbeat.

After enrollment, the terminal prints the local fingerprint and the pending machine appears automatically in Clone Version. Confirm only when the two fingerprints match, then install the persistent outbound agent:

cvbox service install
cvbox status
cvbox doctor

cvbox service install installs an unprivileged LaunchAgent on macOS or a user systemd service on Linux. It starts Node with a clean environment so unrelated terminal or login-session secrets are not inherited by CVBox. Run cvbox start directly when a service manager is not available.

CVBox refuses start, service install, and service start until enrollment has created local machine state. A missing enrollment exits with the exact Machines-page recovery flow instead of retrying as a network failure.

Commands

cvbox enroll --server URL [--name NAME] [--root PATH]
cvbox start
cvbox run --once
cvbox status
cvbox doctor
cvbox roots full|list|add|remove [PATH]
cvbox service install|uninstall|start|stop

Use http://127.0.0.1:3030 only when CVBox runs on the same computer as the local Clone Version API. Remote machines require the deployed HTTPS origin; they cannot use another computer's loopback address.

For non-interactive provisioning, pipe the short-lived code to cvbox enroll --code-stdin. Treat the pipe input as a secret and avoid command logging.

Security model

• Every network request is initiated by CVBox over HTTPS.
• Pairing codes expire after ten minutes, are single-use, and are stored by the server only as a keyed digest.
• The device and control plane sign separate protocol messages with Ed25519.
• Timestamp and nonce checks reject stale or replayed machine requests.
• Commands are typed, short-lived, machine-bound, and signed.
• File operations resolve real paths and stay inside the owner-approved scope; full-computer scope still follows OS permissions and sensitive-path denials.
• Existing files can be changed only by signed fs.write commands carrying an interactive-confirmation marker and the SHA-256 of the previewed version. Writes are bounded and reject conflicts; create, delete, rename, upload, and chmod are not supported by the file API.
• Terminal sessions require the same explicit remembered machine unlock plus an interactive-confirmation marker. CVBox chooses the native shell, limits session count, input, output replay, and dimensions, and keeps the transport outbound-only. Closing a browser tab does not terminate the PTY; explicit deletion does.
• Remote Desktop uses a single outbound WebSocket media session, a one-use relay token, a 15-minute absolute limit, bounded JPEG frames, and one active monitor at a time. It never enables clipboard, audio, recording, printing, file transfer, or unattended access. Control requires a fresh desktop-only confirmation and is not inherited from the file/terminal unlock.
• macOS requires Screen Recording for viewing and Accessibility for control. Windows is limited to the current interactive user desktop. Linux capability detection fails closed when the current X11/Wayland session has no supported capture or input tool; CVBox does not weaken compositor protections.
• Process inspection excludes arguments and environment variables.
• Credentials and internal IDs are never intended for normal UI display.
• There is no inbound listener, SSH key exchange, public RDP/VNC server, or browser-selected executable.

See SECURITY.md before enabling additional machine capabilities.

Development

pnpm --filter @bekirdag/cvbox typecheck
pnpm --filter @bekirdag/cvbox test
pnpm --filter @bekirdag/cvbox build
pnpm --filter @bekirdag/cvbox pack

Matching cvbox-vX.Y.Z tags are qualified and published by the repository's OIDC-backed npm release workflow after the tag version matches this package.