Claude Code transcript - page 1/2

# Web-Based SSH Terminal Solutions: Structured Comparison

## 1. Overview of Main Open-Source Options

### ttyd
- **Language:** C (tiny binary, ~3MB)
- **How it works:** Wraps any command (e.g., `bash`, `login`) in a WebSocket-based terminal accessible from a browser. It does **not** use SSH at all — it directly spawns a process on the host and exposes it over HTTP/WebSocket with an embedded xterm.js frontend.
- **WebSocket support:** Yes, native.
- **Run on target VM:** Yes — this is its primary use case. You run `ttyd bash` on the VM and connect from a browser.
- **Cloud-init friendly:** Extremely. Single static binary, available in most package managers (`apt install ttyd`), or downloadable from GitHub releases. A cloud-init script can install and start it in 3-4 lines.
- **Authentication model:** ttyd itself supports HTTP basic auth (`-c user:pass`), or you can put it behind a reverse proxy with token/cert auth. Since it spawns a local process directly (not SSH), **no SSH keys are involved at all**. The process runs as whatever user starts ttyd (or you can use `ttyd login` to get a PAM login prompt).
- **Key transit through browser:** No. No SSH involved. The browser connects to the ttyd HTTP/WebSocket endpoint; ttyd spawns a shell locally.
- **Pros:**
  - Lightest weight option — single binary, minimal dependencies
  - No SSH overhead; direct PTY allocation
  - Built-in xterm.js client, no browser-side library needed beyond a browser
  - TLS support built in (`--ssl`)
  - Can expose any command, not just shell (e.g., `ttyd htop`)
- **Cons:**
  - No SSH — so you get a shell as whatever user runs ttyd, not a multi-user SSH experience
  - Basic auth is rudimentary; for production you need a reverse proxy for proper auth
  - No built-in session recording or audit logging
  - If ttyd process is compromised, attacker has a shell

---

### wetty (Web + TTY)
- **Language:** Node.js (TypeScript)
- **How it works:** Runs an HTTP/WebSocket server that, on connection, opens an SSH session to a target host (default: localhost). The browser gets an xterm.js terminal. The SSH connection is from the wetty process to the SSH daemon.
- **WebSocket support:** Yes, native.
- **Run on target VM:** Yes. Commonly deployed on the same machine, connecting to `localhost:22`.
- **Cloud-init friendly:** Moderate. Requires Node.js runtime (~60-100MB installed). Install via `npm install -g wetty` or use the Docker image. Cloud-init needs to install Node.js first, then wetty. More steps than ttyd but still manageable (~10 lines of cloud-init).
- **Authentication model:** By default, wetty prompts for SSH username/password in the terminal (the SSH auth happens server-side between wetty and sshd). It can also be configured with `--sshkey` to use a local private key for the SSH connection, in which case the browser user never touches a key. You can put it behind an OAuth proxy or use URL-based auth tokens.
- **Key transit through browser:** **No** (when using `--sshkey`). The private key stays on the VM. The browser only authenticates to the wetty HTTP endpoint (via whatever auth layer you add) and then gets a pre-authenticated SSH session.
- **Pros:**
  - Mature project, well-maintained
  - SSH connection means proper PAM auth, audit trail, session accounting
  - `--sshkey` flag enables the exact pattern of "proxy holds key, browser uses token"
  - Supports custom base paths for reverse proxy setups
  - Docker image available
- **Cons:**
  - Requires Node.js runtime — heavier install than ttyd or Go binaries
  - Node.js can have memory overhead for idle sessions
  - npm dependency tree is a supply-chain surface

---

### sshwifty
- **Language:** Go (single static binary)
- **How it works:** WebSocket-based SSH (and Telnet) client. The Go server acts as a proxy — the browser UI sends SSH connection parameters (host, port, credentials) to the server, which opens the actual SSH connection. The browser-side is a custom JS/WASM client (not xterm.js).
- **WebSocket support:** Yes, native.
- **Run on target VM:** Yes, can run on the target and connect to localhost.
- **Cloud-init friendly:** Very. Single Go binary, download from GitHub releases. Similar to ttyd in ease — 3-5 lines of cloud-init.
- **Authentication model:** This is where sshwifty differs. By default, the **browser user provides SSH credentials** (password or private key) through the web UI, and those are sent to the sshwifty server over WebSocket, which then uses them to connect via SSH. There is a "preset" feature where you can pre-configure SSH connections with credentials stored in a server-side config file — in this mode, the browser user does not provide keys.
- **Key transit through browser:** **Yes by default** (keys are sent from browser to proxy). **No with presets** (keys stored in server config).
- **Pros:**
  - Single binary, easy deployment
  - Supports both SSH and Telnet
  - Presets allow key-on-server pattern
  - Built-in SharedKey authentication for the web interface itself
  - Actively maintained
- **Cons:**
  - Default mode sends credentials through the browser (less secure)
  - Custom UI (not xterm.js) — less familiar, less extensible
  - Preset configuration is JSON file based, less dynamic than API-driven approaches
  - Fewer configuration options than wetty for reverse proxy integration

---

### Apache Guacamole
- **Language:** Java (server) + C (guacd proxy daemon)
- **How it works:** Full remote desktop gateway. The architecture has three components: (1) browser-side JS client, (2) Java web app (guacamole-client), (3) guacd daemon (C, handles the actual SSH/RDP/VNC protocol). The browser speaks the Guacamole protocol over WebSocket to the Java server, which relays to guacd.
- **WebSocket support:** Yes.
- **Run on target VM:** Technically possible but impractical. Requires Java + Tomcat + guacd + database (MySQL/PostgreSQL for connection storage). This is designed as a centralized gateway, not a per-VM agent.
- **Cloud-init friendly:** **No.** Heavy installation: Java/Tomcat, the guacamole WAR file, guacd compilation or package, database setup. Typically deployed via Docker Compose with 3+ containers. Not suitable for ephemeral VM setup.
- **Authentication model:** Very rich — supports LDAP, SAML, OpenID Connect, TOTP, CAS, RADIUS, database auth. SSH keys are stored in the Guacamole database/config, not sent from the browser. The browser authenticates to Guacamole (the gateway), and Guacamole handles the SSH session with pre-configured credentials.
- **Key transit through browser:** **No.** Keys are managed server-side in the connection configuration.
- **Pros:**
  - Enterprise-grade: session recording, audit logging, concurrent access, clipboard sharing
  - Supports SSH, RDP, VNC, Telnet, Kubernetes
  - Rich auth integration (SAML, OIDC, LDAP)
  - Connection sharing and monitoring
- **Cons:**
  - Very heavy — not suitable for per-VM deployment or cloud-init
  - Complex architecture (3+ components)
  - High resource usage (Java + database)
  - Overkill for single-VM shell access

---

### GoTTY
- **Language:** Go (single binary)
- **How it works:** Very similar to ttyd — wraps a command in a WebSocket terminal. `gotty bash` exposes a shell over HTTP.
- **WebSocket support:** Yes.
- **Run on target VM:** Yes.
- **Cloud-init friendly:** Yes — single binary.
- **Authentication model:** Basic auth via flags. No SSH involvement (same as ttyd). However, GoTTY is **largely unmaintained** (last significant commit was ~2017, archived on GitHub).
- **Key transit through browser:** No (no SSH).
- **Note:** ttyd was created as an actively-maintained alternative to GoTTY. **Use ttyd instead.**

---

### webssh / webssh2
- **Language:** Python (webssh) / Node.js (webssh2)
- **How it works:** Browser-based SSH client. The browser provides SSH credentials (host, user, password/key) through a web form, sends them to the server, which opens an SSH connection.
- **WebSocket support:** Yes.
- **Cloud-init friendly:** Moderate (Python/Node.js dependency).
- **Authentication model:** By default, credentials are sent from browser to server. webssh2 (used by ManageEngine, etc.) can be configured with host-side keys.
- **Key transit through browser:** **Yes by default.**
- **Pros:** Simple, focused on SSH specifically
- **Cons:** Default model requires browser to send keys; less maintained than alternatives

---

## 2. Structured Comparison Table

| Feature | ttyd | wetty | sshwifty | Guacamole | GoTTY |
|---|---|---|---|---|---|
| **Language** | C | Node.js | Go | Java+C | Go |
| **Binary size** | ~3MB | ~60MB (with Node) | ~15MB | ~500MB+ | ~10MB |
| **Uses SSH** | No (direct PTY) | Yes | Yes | Yes | No (direct PTY) |
| **WebSocket** | Yes | Yes | Yes | Yes | Yes |
| **On-VM deployment** | Excellent | Good | Excellent | Poor | Excellent |
| **Cloud-init lines** | 3-5 | 8-12 | 3-5 | 30+ | 3-5 (but unmaintained) |
| **Key in browser** | N/A | No (with --sshkey) | Yes (default) / No (presets) | No | N/A |
| **Auth options** | Basic/reverse proxy | SSH + proxy layer | SharedKey + SSH | LDAP/SAML/OIDC/DB | Basic |
| **Maintained** | Active | Active | Active | Active | Archived |
| **xterm.js** | Yes (built-in) | Yes (built-in) | Custom UI | Custom protocol | Yes (built-in) |

---

## 3. The "Proxy Holds Key, Browser Uses Token" Pattern

This is the most security-conscious architecture, and yes, it is a well-established pattern. Here is how it works:

### Architecture
```
Browser  --[HTTPS/WSS + auth token]--> WebSocket Proxy (on VM)
                                            |
                                    [local SSH key on disk]
                                            |
                                       SSH to localhost:22
```

### Which tools support this natively:

1. **ttyd** — achieves this without SSH entirely. Run `ttyd -c token:secret bash` or put it behind a reverse proxy that validates a short-lived JWT. The shell is direct, no SSH key involved at all.

2. **wetty** — run with `wetty --sshkey /path/to/key --sshuser deploy --sshhost localhost`. The SSH key lives on disk, wetty uses it to connect to local sshd. Put wetty behind an auth proxy (e.g., oauth2-proxy) that validates a token. The browser never sees the SSH key.

3. **sshwifty** — use presets in the config JSON:
   ```json
   {
     "Presets": [{
       "Type": "SSH",
       "Host": "localhost:22",
       "User": "deploy",
       "PrivateKey": "/path/to/key"
     }]
   }
   ```
   The web interface uses SharedKey authentication (a shared secret/token). Browser never sees the SSH key.

4. **Custom approach** — run a lightweight WebSocket server (e.g., using xterm.js addon-attach on the browser side) that authenticates via a signed token and then opens an SSH connection or PTY locally. Libraries like `ssh2` (Node.js) or Go's `x/crypto/ssh` make this straightforward.

### Short-lived token implementation patterns:
- **Pre-shared token in cloud-init:** Generate a random token during VM provisioning, pass it as an env var or config file to the proxy. Share the token with the user via your control plane.
- **TLS client certificates:** Generate a short-lived client cert during provisioning, provide it to the user's browser. The proxy validates the cert. This is the strongest option but more complex to implement.
- **JWT signed by control plane:** Your orchestrator signs a JWT with a short expiry. The proxy validates the signature against a known public key. No shared secret needed.

---

## 4. Recommendations by Use Case

### For this project (cloud-init on fresh VMs, browser-side terminal):

**Best option: ttyd**
- Rationale: Lightest weight, no SSH needed (direct shell), trivial cloud-init setup, built-in xterm.js. Put it behind a token-validated reverse proxy or use its basic auth with a generated secret.
- Cloud-init example:
  ```yaml
  runcmd:
    - apt-get update && apt-get install -y ttyd
    - ttyd -p 7681 --writable -c "token:$(cat /etc/ttyd-secret)" bash &
  ```

**Runner-up: wetty with --sshkey**
- Rationale: If you need SSH semantics (PAM accounting, user switching, audit logs), wetty with a local key is the best option. Slightly heavier install but proven pattern.

**Avoid for this use case:**
- Guacamole — too heavy for per-VM deployment
- GoTTY — unmaintained
- sshwifty default mode — sends credentials through browser
- webssh — sends credentials through browser

### If you need maximum security:
Use **ttyd** or **wetty** behind a reverse proxy (e.g., Caddy or nginx) that validates JWTs issued by your control plane. The proxy terminates TLS with a Let's Encrypt cert (Caddy does this automatically). The ttyd/wetty process binds only to localhost. This gives you:
- TLS encryption in transit
- Short-lived token authentication
- No SSH keys in the browser
- No SSH keys in transit at all (with ttyd, no SSH period)

agentId: af4ee28fab40e34e0 (use SendMessage with to: 'af4ee28fab40e34e0' to continue this agent)
<usage>total_tokens: 12371
tool_uses: 0
duration_ms: 84170</usage>

Perfect! Now let me create a comprehensive summary document based on my exploration:

## Comprehensive Codebase Analysis Report

I've completed a thorough exploration of the Stirlingbridge local-orchestrator project and related infrastructure. Here's what I found:

---

## 1. VM/Machine Creation Architecture

**Location:** `/home/david/projects/stirlingbridge/machine/` (separate repository)

### Cloud-Init & SSH Key Provisioning

The machine tool uses **cloud-init** for VM provisioning:

**Key Files:**
- `/home/david/projects/stirlingbridge/machine/machine/cloud_config.py` - Generates cloud-config YAML with:
  - User creation with sudo access (`new_user_name`)
  - SSH public key injection from the provider's SSH key store
  - Optional `runcmd` section that downloads and executes setup scripts
  - Environment variable substitution via `expandvars`

**Cloud-Init Features:**
- Creates a dedicated user with passwordless sudo
- Injects SSH public key for authentication
- Downloads and executes setup scripts if `script_url` is provided
- Passes environment variables to the initialization script via cloud-config's `runcmd`

### VM Creation Process

**DigitalOcean Provider** (`/home/david/projects/stirlingbridge/machine/machine/providers/digitalocean.py`):
1. Looks up SSH key by name from DigitalOcean account
2. Creates a `digitalocean.Droplet` object with:
   - `name` - VM name
   - `region` - Geographic region (NYC1, SFO3, AMS3, etc.)
   - `image` - OS image (Ubuntu 24.04, Debian 12, CentOS, AlmaLinux, etc.)
   - `size_slug` - Machine size (s-1vcpu-1gb, s-4vcpu-8gb, etc.)
   - `ssh_keys` - List containing the SSH key object
   - `tags` - For tracking (session ID, machine type, creation tag)
   - `user_data` - The cloud-init config from `cloud_config.py`
3. Calls `droplet.create()` which triggers DigitalOcean's API
4. Polls for IP address assignment (up to 60 seconds)
5. Optionally creates DNS A records if DNS zone configured

**Create Command** (`/home/david/projects/stirlingbridge/machine/machine/subcommands/create.py`):
- Supports flags: `--name`, `--region`, `--image`, `--machine-size`, `--type`, `--tag`
- Validates SSH key exists before creation
- Supports `--wait-for-ip` and `--update-dns` flags
- Returns droplet ID and IP address

---

## 2. Runtime/Worker Architecture

**Location:** `/home/david/projects/stirlingbridge/local-orchestrator/src/`

### Browser-to-External Communication Pattern

The architecture uses **Pyodide (WASM Python)** with custom HTTP modules to bypass WASM socket limitations:

**Key Components:**

1. **BrowserRuntime** (`runtime.ts`):
   - Public API class managing worker communication
   - Methods: `init()`, `exec()`, `registerCommand()`, `installPackages()`, `writeFile()`, `readFile()`
   - Implements request/response correlation with unique IDs
   - Tracks installed dependencies to avoid reinstalling

2. **Web Worker** (`worker.ts`):
   - Hosts Pyodide instance (Python interpreter compiled to WASM)
   - Manages in-memory virtual filesystem (`/tools/` for Python scripts)
   - Provides HTTP client shims:
     - **`http_client` module**: Uses synchronous XMLHttpRequest via Pyodide FFI
     - **`requests` shim**: Wraps http_client to provide requests API compatibility
   - Handles message types: `init`, `exec`, `install`, `write-file`, `read-file`

3. **Bootstrap Python**:
   - Runs `_run_command(script_path, args_json)` helper
   - Captures stdout/stderr/exitCode
   - Properly handles `sys.argv`, environment variables, and SystemExit

### Message Protocol (Types in `types.ts`)

```typescript
WorkerRequest = 
  | { id, type: "init" }
  | { id, type: "exec", scriptPath, args, env? }
  | { id, type: "install", packages }
  | { id, type: "write-file", path, content }
  | { id, type: "read-file", path }

WorkerResponse =
  | { id, type: "ready" }
  | { id, type: "exec-result", stdout, stderr, exitCode }
  | { id, type: "install-result", success, error? }
  | { id, type: "write-file-result", success, error? }
  | { id, type: "read-file-result", success, content?, error? }
  | { id, type: "error", error }
```

### Command Registration System

- **Simple commands**: Python source code written to `/tools/{name}.py`, registered via `registerCommand()`
- **Package commands**: Multi-file packages with entry point via `registerPackageCommand()`
- **GitHub commands**: Auto-discovered from GitHub repos via `registerGitHubCommand()` using GitHub API
- **Repository cloning**: Full GitHub repos cloned to virtual filesystem via `cloneRepo()`

### Environment & Secrets

**SecretStore** (`secrets.ts`):
- AES-GCM encrypted storage using Web Crypto API
- Non-extractable CryptoKey stored in IndexedDB
- Ciphertext persisted in localStorage (origin-scoped)
- All secrets injected as environment variables to every command execution

---

## 3. Terminal UI Code

**Location:** `/home/david/projects/stirlingbridge/local-orchestrator/`

### Terminal Interface (`main.ts`)

**DOM Structure** (from `index.html`):
- Header with title and Secrets button
- Status bar showing runtime state (Loading, Ready, Error)
- Output area (scrollable, pre-formatted)
- Input bar with command prompt
- Example buttons for quick commands
- Secrets modal (encrypted key/value storage)

**Terminal Features:**
- Command parsing with quote handling (`parseCommand()`)
- Line coloring by type:
  - `line-stdout`: Default text
  - `line-stderr`: Red errors
  - `line-cmd`: Green for executed commands
  - `line-info`: Blue for info messages
  - `line-exit-ok`/`line-exit-err`: Exit codes
- Status bar with state indicators (ready=green, error=red)

**Built-in Commands** (`commands.ts`):
- `hello [--name NAME] [--shout]` - Argparse demo
- `sysinfo` - Python/platform info
- `fetch URL [--headers]` - HTTP fetch with custom http_client
- `env [NAME] [--filter STR]` - Environment variables
- `files [PATH] [-r]` - Virtual filesystem listing

**Extensible Commands**:
- `test-tool` - Loaded from `bozemanpass/test-python-cli-tool` on startup
- `machine` - Loaded from `stirlingbridge/machine` on startup (see below)
- Custom commands via `runtime.registerCommand()`

### Secrets Modal UI

- Modal overlay with key/value input fields
- Password field for secret values
- Delete button for each secret
- "Add" button to encrypt and store
- All encrypted client-side, never sent to backend

**Styling**: Tokyonight dark theme (colors from `index.html` inline styles)

---

## 4. Types & Message Protocol Summary

### Public API Types (`types.ts`)

```typescript
// Command registration
CommandDef {
  source: string;        // Python source code
  dependencies?: string[]; // Packages to install
  scriptPath?: string;   // Override default /tools/{name}.py
}

PackageCommandDef {
  files: Record<string, string>;  // File paths -> contents
  entryPoint: string;              // "module.path:function"
  dependencies?: string[];
}

GitHubCommandOptions {
  repo: string;        // "owner/repo"
  branch?: string;     // Default: "main"
  subdir?: string;     // Subdirectory in repo
  entryPoint: string;  // Entry point in package
  dependencies?: string[];
}

// Execution
ExecOptions {
  stdin?: string;
  env?: Record<string, string>;
  cwd?: string;
}

ProcessResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}
```

### Machine Tool Integration

The `machine` command is registered on startup (`main.ts` lines 307-326):

```typescript
runtime.registerGitHubCommand("machine", {
  repo: "stirlingbridge/machine",
  entryPoint: "machine.main:main",
  dependencies: ["click", "python-digitalocean", "ruamel.yaml", "expandvars"],
});

// Default config written to virtual filesystem
await runtime.writeFile("/home/pyodide/.machine/config.yml", 
  "digital-ocean:\n  access-token: ${DIGITALOCEAN_ACCESS_TOKEN}\n..."
);
```

The machine tool's Click CLI exposes subcommands:
- `machine create --name <NAME> --type <TYPE>` - Creates VM
- `machine list` - Lists VMs
- `machine destroy <VM-ID>` - Destroys VM
- `machine ssh-keys` - Lists SSH keys
- `machine domains` - Lists DNS zones
- `machine status <VM-ID>` - Gets VM status

---

## Key Design Patterns

1. **Worker Isolation**: Python execution in Web Worker keeps UI responsive
2. **HTTP Bypass**: Custom http_client module uses browser's XHR instead of Python sockets to work in WASM
3. **Requests Compatibility**: Shim layer lets `python-digitalocean` work unchanged
4. **Virtual Filesystem**: In-memory, no disk I/O, scripts and packages stored as strings
5. **Lazy Loading**: Pyodide and external tools loaded on demand, not bundled
6. **Environment Injection**: Secrets stored securely, injected as env vars at execution time

---

## File Paths Reference

**Local Orchestrator:**
- `/home/david/projects/stirlingbridge/local-orchestrator/src/main.ts` - UI wiring
- `/home/david/projects/stirlingbridge/local-orchestrator/src/runtime.ts` - Browser runtime API
- `/home/david/projects/stirlingbridge/local-orchestrator/src/worker.ts` - Pyodide worker & HTTP modules
- `/home/david/projects/stirlingbridge/local-orchestrator/src/types.ts` - Type definitions
- `/home/david/projects/stirlingbridge/local-orchestrator/src/commands.ts` - Built-in demo commands
- `/home/david/projects/stirlingbridge/local-orchestrator/src/secrets.ts` - Encrypted secret store
- `/home/david/projects/stirlingbridge/local-orchestrator/index.html` - UI template

**Machine Tool:**
- `/home/david/projects/stirlingbridge/machine/machine/main.py` - Click CLI entry point
- `/home/david/projects/stirlingbridge/machine/machine/cloud_config.py` - Cloud-init generation
- `/home/david/projects/stirlingbridge/machine/machine/providers/digitalocean.py` - DO API wrapper
- `/home/david/projects/stirlingbridge/machine/machine/subcommands/create.py` - VM creation logic
- `/home/david/projects/stirlingbridge/machine/machine/config.py` - Config file parsing