workbench-server/INSTALL.md

Workbench — AI-Guided Setup

You are an AI assistant helping a user set up Workbench. Follow these steps in order. Do not ask the user what they have — detect it yourself. Present options conversationally.

Step 0: Clone and Install

If the repo is not already cloned locally, clone it:

git clone <repo-url>
cd workbench-server

Install the package:

pip install .

If pip install fails due to PEP 668, use:

pip install --break-system-packages .

Verify it installed:

workbench --version

If already installed, skip to Step 1.

Step 1: Detect the Environment

Run these commands and collect the output. Do NOT ask the user:

# Python
python3 --version

# Platform
uname -s -r -m

# Access topology
echo "SSH_CONNECTION=$SSH_CONNECTION"

# SSH usage detection
ls ~/.ssh/config 2>/dev/null && echo "ssh config: found" || echo "ssh config: not found"
grep -l "ControlMaster\|ControlPath" ~/.ssh/config 2>/dev/null && echo "ssh multiplexing: configured" || echo "ssh multiplexing: not configured"
ls ~/.ssh/known_hosts 2>/dev/null && wc -l < ~/.ssh/known_hosts 2>/dev/null && echo "known hosts (suggests SSH usage)" || true

Step 2: Create Project Directory

mkdir -p ~/workbench

Step 3: Configure SSH ControlMaster (if applicable)

If the user SSHes to remote machines (detected by known_hosts having entries, or the user mentions remote work), set up SSH connection multiplexing so the AI CLI can reuse authenticated SSH connections without needing to re-enter passwords or touch physical keys.

Ask the user: "Do you SSH into remote machines as part of your work? If so, I can configure SSH connection multiplexing — this lets you authenticate once, and my SSH commands piggyback on your open connection without needing a password."

If yes:

mkdir -p ~/.ssh/sockets
chmod 700 ~/.ssh/sockets

Check if ControlMaster is already configured:

grep -q "ControlMaster" ~/.ssh/config 2>/dev/null && echo "Already configured" || echo "Not configured"

If not configured, add to ~/.ssh/config (create if needed):

touch ~/.ssh/config
chmod 600 ~/.ssh/config
cat >> ~/.ssh/config << 'SSHEOF'

# Workbench: SSH connection multiplexing
# First connection authenticates normally (password, key, etc.)
# Subsequent connections reuse the tunnel — no re-auth needed
Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist yes
SSHEOF

Explain to the user how it works:

How this works: When you SSH into a remote machine, the connection stays open in the background. During that time, any other SSH command to the same host — including ones I run — reuses your authenticated tunnel. No password prompt, no key tap. The tunnel stays open until the original session closes or the connection drops — your key/auth provider handles its own timeout. Just open an SSH session to your target machine before asking me to work on it.

If the user's ~/.ssh/config already has Host-specific blocks, add the ControlMaster settings under a Host * block at the end of the file so it acts as a default without overriding specific host configs.

Step 4: Configure MCP

Add the Workbench MCP server to the user's AI CLI configuration.

Detect which CLI they're using by checking for config files:

ls ~/.claude/settings.json 2>/dev/null && echo "Claude Code detected"
ls ~/.gemini/settings.json 2>/dev/null && echo "Gemini CLI detected"
ls ~/.config/gemini/settings.json 2>/dev/null && echo "Gemini CLI detected (alt path)"

The MCP server configuration:

{
  "mcpServers": {
    "workbench": {
      "command": "workbench",
      "args": ["mcp"]
    }
  }
}

Add this to the appropriate config file for the detected CLI. For unknown CLIs, print the JSON and tell the user to add it to their MCP settings. The server command is workbench mcp on stdio transport.

Step 5: Smoke Test

workbench list

Should print "No projects found in ~/workbench/" (or list existing projects if any).

Step 6: Write START.md

Write ~/workbench/START.md — a personalized startup guide for this user's environment.

Include:

• Setup date
• Platform details
• MCP configuration that was applied (which CLI, what config)
• How to start a session
• SSH ControlMaster status
• How to access the workbench page (open URL in browser)

Example:

# Workbench — Start Guide

**Setup date:** 2026-03-30
**Platform:** Linux (Ubuntu 24.04)

## Starting a Session

1. Start your AI CLI
2. Ask the AI to create a workbench project — it calls `workbench_scaffold` and returns a URL
3. Open the URL in your browser
4. The AI pushes content to the page in real-time

## MCP Configuration

Configured in `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "workbench": {
      "command": "workbench",
      "args": ["mcp"]
    }
  }
}

Environment

• Python: 3.11.4
• SSH ControlMaster: configured

Notes

• The HTTP server binds to 0.0.0.0 — open the URL from any device on your LAN
• If you restart your AI CLI, the server keeps running — just call workbench_scaffold again
• Session logs are saved in ~/workbench//session.md

Adapt the content to match what you actually detected and configured. This file is for future AI sessions to read, so be precise.

## Done

Tell the user setup is complete and how to start their first session.