cmd-agent

The local MacBook agent for cmd.cvasingh.com — Remote Terminal Control.

Connects to cmd.cvasingh.com and spawns real PTY sessions on your machine, bridging your browser to a live terminal over WebSocket.

How it works

Browser (xterm.js)
  ↕  Ably channel: terminal:{sessionId}
cmd-agent (node-pty on your Mac)
  ↕  Ably channel: control:{deviceId}
Next.js backend (cmd.cvasingh.com)

No API keys to configure — the agent authenticates by logging in through your browser. A deviceId is issued on approval and saved locally.

Requirements

• Node.js 18+
• macOS (Linux also works)

Install

npm install -g cmd-agent

Usage

First run

cmd-agent

You will be asked for one thing:

Device name (e.g. My MacBook) :

The agent opens cmd.cvasingh.com/connect in your browser. Log in with your account, click Approve Device, and the agent connects automatically.

Config is saved to ~/.cmd-agent (readable only by you).

Subsequent runs

cmd-agent

Reads saved config and starts immediately — no prompts.

Commands

| Command | Alias | Description | |---|---|---| | cmd-agent | | Start the agent | | cmd-agent --login | -l | Re-run browser login (keeps device name) | | cmd-agent --logout | | Clear saved login, require re-login on next start | | cmd-agent --reconfigure | -r | Full reset: re-enter device name + re-login | | cmd-agent --status | | Show current device name, ID, and config path | | cmd-agent --version | -v | Show installed version | | cmd-agent --help | -h | Show help |

Re-login (same device, new session)

cmd-agent --login

Switch account or revoke and re-approve

cmd-agent --logout   # clears deviceId
cmd-agent            # triggers login flow again

Full reset (rename device + new login)

cmd-agent --reconfigure

Running in the background with pm2

npm install -g pm2
cmd-agent                               # complete browser login first, then Ctrl-C
pm2 start $(which cmd-agent) --name cmd-agent
pm2 save
pm2 startup                             # auto-start on login

Config file

~/.cmd-agent is managed automatically:

{
  "deviceName": "My MacBook",
  "deviceCode": "...",
  "deviceId": "..."
}

Delete this file or run cmd-agent --logout to start fresh.

Author

Shiva Singh — cvasingh

License

MIT