@myanalyticsschool/connect

Mirror your local terminal into a MAS Class lesson on myanalyticsschool.com.

When a MAS Class lesson asks you to connect your machine, you'll see a session token. Run:

npx -y @myanalyticsschool/connect <session-token>

A real shell starts. Anything you type is shown in the lesson page in your browser. The lesson can highlight commands, follow along, or — in bidirectional mode — type into your shell directly.

Type exit to disconnect.

What this is for

MAS Class teaches things like "install Redis on your machine" or "set up your dev environment". Sandboxed cloud terminals are useless for these — the student wants the software on their actual laptop when the lesson ends. @myanalyticsschool/connect is the bridge: a one-command CLI that opens a real shell on your machine and mirrors it into the browser lesson.

Install / use

No install needed if you have Node 18+:

npx -y @myanalyticsschool/connect <session-token>

Or install globally:

npm i -g @myanalyticsschool/connect
mas-connect <session-token>

Options

mas-connect <session-token> [options]

  --read-only         Browser only watches; cannot send keystrokes
  --relay <wss-url>   Override the relay endpoint
                      (env: MAS_CONNECT_RELAY_URL)
  --shell <path>      Override the shell that gets spawned
  --no-confirm        Skip the safety prompt (NOT recommended)
  -h, --help          Show help
  -v, --version       Show CLI version

Safety

Before doing anything, the CLI prints a banner and waits for Enter. The banner shows:

• The relay endpoint it's about to dial
• The shell it will spawn ($SHELL by default)
• Working directory
• Whether the lesson can type into your shell (bidirectional) or only watch (read-only)

Press Ctrl-C at the prompt to abort.

Bidirectional vs read-only

By default, the lesson page can also type into your shell. This is what makes "follow along" lessons work — the lesson clicks "Run", and the command appears in your terminal. It also means anything that gets sent runs as you, on your machine.

If you'd rather drive the keyboard yourself and have the lesson only watch:

npx -y @myanalyticsschool/connect <token> --read-only

What we won't do

• We won't auto-fetch tokens from URLs. You must paste it.
• We won't run without showing the safety prompt unless you pass --no-confirm.
• We won't keep the session open after the shell exits.

What you should do

• Get tokens only from the official lesson page on myanalyticsschool.com. Never run @myanalyticsschool/connect with a token from anywhere else — it grants whoever set up that session keystroke access to your machine if you're in bidirectional mode.
• Treat the session like a SSH session: don't run it in a directory that has anything you don't want a stranger to see, in case the session token leaks.
• Type exit when done.

How it works

Browser (xterm.js)  ←──── WebSocket relay ────→  mas-connect CLI ←──→ PTY (your shell)
                            on api.mrmentor.in

The CLI:

1. Validates args + shows safety banner.
2. Opens a WebSocket to the relay, sends { type: 'auth', token, ... }.
3. On { type: 'ready' } from the relay, spawns a node-pty running your shell.
4. Pipes stdio bytes both ways:
   • PTY stdout → local stdout and binary frame to relay
   • Browser keystrokes (from the relay) → PTY stdin (skipped if --read-only)
5. Forwards local terminal resize events to both the PTY and the peer.
6. Cleans up on PTY exit, peer disconnect, Ctrl-C at the prompt, or SIGTERM.

Wire protocol

Frames carry one of two payloads:

• TEXT frames: JSON control messages.
• BINARY frames: raw stdio bytes.

Control messages:

| Direction | Type | Purpose | |---|---|---| | C → S | { type: 'auth', token, version, readOnly, cols, rows } | First frame; authenticates the CLI half. | | S → C | { type: 'ready' } | Auth accepted; CLI may begin streaming. | | S → C | { type: 'error', code, message } | Auth rejected; CLI exits non-zero. | | C → S | { type: 'resize', cols, rows } | Local terminal resized. | | S → C | { type: 'peer-resize', cols, rows } | Browser resized; CLI resizes the PTY. | | S → C | { type: 'peer-disconnect' } | Browser left; CLI keeps the shell open. | | Either | { type: 'close', reason? } | Graceful close. |

Companion: full-IDE mirror

If your lesson needs a full editor (file tree, multi-file editing, integrated terminal) rather than just a shell, use the IDE companion: @myanalyticsschool/connect-ide. It runs code-server locally and exposes it to the lesson via a Cloudflare Quick Tunnel.

| | connect | connect-ide | |---|---|---| | What's mirrored | One shell (PTY bytes) | Full VS Code (HTTPS iframe) | | Local tool needed | Just Node | code-server + cloudflared | | Bytes in iframe path | Browser ↔ relay ↔ CLI | Browser ↔ Cloudflare ↔ local | | Off-by | exit in shell | Ctrl-C in this CLI |

Both use the same relay and session token — the lesson scene picks which mode to use.

Requirements

• Node.js 18+
• macOS / Linux / Windows (node-pty ships prebuilds; build tools needed only on uncommon arches)
• An active MAS Class lesson session on myanalyticsschool.com

Development

git clone https://github.com/MAS-Mr-Mentor/mas-connect.git
cd mas-connect
npm install
npm run build
node dist/cli.js --help

# Point at a local relay while developing
MAS_CONNECT_RELAY_URL=ws://localhost:8000/api/terminal/relay node dist/cli.js <token>

Publishing

npm run build
npm publish --access public

The prepublishOnly script runs tsc for you.

License

MIT — see LICENSE.