@starciacademy/playground-agent

@starciacademy/playground-agent

The bring-your-own-machine (BYOM) CLI agent for StarCi Academy Docker / Kubernetes playgrounds.

StarCi playground labs run on your own machine — there is no hosted sandbox. When you open a Docker or Kubernetes lab, the browser shows a pairing code. Run this agent with that code and it will:

1. Pair your terminal with the playground session.
2. Relay the commands you run through the lesson back to the browser terminal view.
3. Report your local Docker / Kubernetes resources so each step verifies automatically when the expected container / pod / service appears.

Usage

npx @starciacademy/playground-agent <pairingCode>

Point it at a non-default server (self-hosted / local dev):

npx @starciacademy/playground-agent <pairingCode> --server http://localhost:3001
# or
STARCI_PLAYGROUND_SERVER=http://localhost:3001 npx @starciacademy/playground-agent <pairingCode>

Run as a background service (optional)

By default the agent runs in your terminal and stops with Ctrl-C. If you want it to keep running and auto-restart (e.g. after a crash or a reboot/login), install it as an OS-managed background service. It uses only built-in OS tooling — no extra native dependency (no node-windows / nssm):

• Windows — a Task Scheduler task (schtasks) that runs at logon and restarts on failure.
• Linux — a systemd user unit with Restart=always.
• macOS — a launchd user agent with KeepAlive=true.

# install, paired to a specific session's code
npx @starciacademy/playground-agent --install-service <pairingCode>

# point it at a non-default server
npx @starciacademy/playground-agent --install-service <pairingCode> --server http://localhost:3001

# remove it
npx @starciacademy/playground-agent --uninstall-service

Caveat: the service is tied to ONE pairing code

The agent pairs into a single playground session identified by its pairing code, so the service is installed with that exact code baked in. It is not a generic always-on agent — it re-attaches to that one session. When you move to a different session (a new code), --uninstall-service and reinstall with the new code.

Security

The service runs the browser-driven command relay unattended: it executes shell commands issued by that one paired session. Only install it on a machine you trust and for a session you started yourself. Uninstall it when you are done. On Linux, a user unit stops at logout unless you enable lingering (loginctl enable-linger $USER).

Requirements

• Node.js ≥ 18
• docker and/or kubectl on your PATH (whichever the lab needs — a Docker-only lab does not need Kubernetes).

What it runs

The agent executes the shell commands issued from your own paired playground session and reports the output + a snapshot of your local Docker/Kubernetes resources (container / image / pod / deployment / service / node / namespace / … names + status). It only connects to the session whose pairing code you provide. Stop it any time with Ctrl-C.

License

MIT