@bekirdag/cvbox

CVBox

@bekirdag/cvbox is the secure, outbound-only machine agent for Clone Version. It lets an invited Clone Version owner inspect approved folders, repository status, machine health, and a redacted process inventory without exposing an inbound port or a generic remote shell.

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 --root /absolute/project/path

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.

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 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 owner-approved roots.
• 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.