@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 text files after an explicit interactive unlock, view repository status and machine health, and inspect a redacted process inventory without exposing an inbound port or a generic remote shell. Sensitive credential stores remain denied.

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.cloudversion.com

Paste the pairing code into the hidden prompt. 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.

Install the persistent outbound agent, then confirm the fingerprint:

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.

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 UTF-8 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 limited to 1 MiB and reject conflicts; create, delete, rename, upload, chmod, and arbitrary shell operations are not supported.
• Process inspection excludes arguments and environment variables.
• Credentials and internal IDs are never intended for normal UI display.
• There is no arbitrary command endpoint, inbound listener, or remote shell.

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.