winkterm-remote

WinkTerm Remote Terminal

Operate WinkTerm's terminals over MCP, CLI, or HTTP fallback. The backend keeps a dedicated PTY per terminal; you can open local or SSH terminals, run commands, read output, run managed long commands, and move files over SSH.

Prefer MCP when the client supports it. winkterm-mcp exposes tools such as winkterm_ssh_run, winkterm_exec, winkterm_snapshot, and generic winkterm_call, while reusing the same WebSocket-first transport as the CLI. If MCP is unavailable, use the CLI. Both carry the agent surface over one WebSocket with a 15s application-level heartbeat, so long commands (installs, builds, dumps) survive a reverse proxy's default ~60s idle read-timeout. CLI calls print live progress frames to stderr as remote terminal output arrives. MCP receives the same progress frames underneath, but the current MCP tools collect them and return {result, progress} only when the tool call finishes; do not assume MCP clients display remote terminal output live. When live human monitoring matters, use the CLI or subscribe to terminal.stream. When the WebSocket is unavailable they transparently fall back to the HTTP API.

Important: WebSocket keepalive prevents connection timeouts; it does not guarantee that the current agent runtime can see CLI stderr/progress while a process is still running. For long tasks, do not blindly wait on one huge timeout. Start the work, then actively observe it with run_wait or snapshots. Background work still needs inspection so prompts, errors, and stuck installs are caught early.

# Install from npm (no clone needed):
npx winkterm help          # run without installing; or: npm install -g winkterm

# Store credentials once (-> ~/.winkterm/cli.json, mode 0600) so later commands
# carry no token on the command line and a screenshot can't leak it:
npx winkterm login --base-url https://your-backend --token <bearer-token>

# MCP-capable clients can run:
npx -y winkterm mcp

# Generic call (covers every method) — long task stays alive over WS:
npx winkterm exec <terminal_id> "sleep 300 && echo done"
npx winkterm run <terminal_id> "docker build ."

This skill is a thin bootstrap. The authoritative, always-current reference (full CLI method map + HTTP fallback surface) lives on the backend at GET /api/agent/skill.md — fetch it on first use so you have the exact surface for the version you are talking to.