Claude Code transcript

Here's what the project contains:

Structure: All scripts live in scripts/ and are designed to be run standalone or composed via combine.sh.

Existing scripts: | Script | Purpose | |--------|---------| | combine.sh | Orchestrator — chains scripts with per-script args | | docker.sh | Docker from official repo | | podman.sh | Podman container runtime | | packages.sh | Generic apt package installer | | k3s-node.sh | Single-node k3s + nginx ingress + cert-manager | | stack.sh | Stack deployment tool | | health.sh | Cloud-init health check HTTP server | | fqdn.sh | Set FQDN from env var | | error.sh | Test script (intentional failure) |

Conventions the scripts follow: - set -eo pipefail for error handling - MACHINE_SCRIPT_DEBUG env var enables set -x - DEBIAN_FRONTEND=noninteractive + NEEDRESTART_MODE=a - Standard APT_INSTALL alias with sudo --preserve-env=... - maybe_install() helper to skip already-installed packages - Idempotency checks (which <tool> before installing, -f to force) - Clear logging with separator lines and echo "$0 called with $*" - getopts or while/case for argument parsing

Now — what web remote access service did you have in mind? (e.g. Apache Guacamole, Cockpit, Teleport, Meshcentral, something else?)

Good set of requirements. Let me break down the landscape and give you a recommendation.

Key Options

Recommendation: ttyd + Caddy with mTLS

ttyd is the strongest fit for your requirements:

• Lightweight: Written in C against libwebsockets. No runtime dependencies (no Node, Python, Java). Available as a distro package or single binary.
• WebSocket native: Clean, documented WebSocket protocol. Messages are type-prefixed: 0 + data for stdin/stdout, resize messages, etc.
• Interactive shell: Bundles xterm.js — full terminal experience out of the box.
• Programmatic use: Browser JS can open a raw WebSocket to the same endpoint, send commands, and read output. The protocol is simple enough to drive from code.
• User context: Can be launched as a specific user (e.g. sudo -u appuser ttyd bash), or you can use --credential to map to a login session.
• No built-in auth to worry about: It delegates that entirely to the reverse proxy, which is what you want.

Caddy as reverse proxy handles:

• mTLS (mutual TLS): During cloud-init, you install only the CA certificate (public). Clients authenticate with certificates signed by that CA. No shared secret ever passes through the provisioning chain.
• TLS termination: Automatic HTTPS.
• Simple config: Caddy's mTLS configuration is much more concise than nginx's.

Architecture

Browser (xterm.js / JS code)
    │
    │  wss:// + client cert
    ▼
  Caddy (mTLS termination, reverse proxy)
    │
    │  ws://localhost:7681
    ▼
  ttyd (runs bash as non-root user)

How the two use cases work

Interactive shell: User opens the page, xterm.js connects via WebSocket, full terminal experience.

Programmatic command exec: Browser JS opens a WebSocket directly to the same endpoint. ttyd's protocol is: - Send: 0 + command + \n (stdin) - Receive: 0 + output (stdout)

The challenge is that stdout includes prompts and ANSI escape codes. Two mitigations: 1. Set TERM=dumb to suppress most escapes 2. Use sentinel markers — e.g. wrap commands as echo __START__; yourcommand; echo __END__ $? — so your JS can extract clean output and exit codes

This isn't as clean as a dedicated exec API, but it means one component on the Linux side instead of two, and the same auth infrastructure covers both paths.

What the provisioning script would install

1. ttyd (apt package or binary download)
2. Caddy (from official repo)
3. A Caddy config with mTLS + reverse proxy to ttyd
4. A systemd unit to run ttyd as the target user
5. Drop the CA certificate into place (the only secret-adjacent material, and it's public)

Want me to go ahead and write this script following the project's conventions? I'd also want to confirm: are you okay with Caddy, or do you have a preference for nginx (which is already pulled in by k3s-node.sh)?

You're right to question this — let me clarify.

mTLS and client certificates are the same thing, yes. And you're right that client certs have significant friction:

• Browsers have clunky UX for managing them (OS certificate store, import dialogs, per-browser differences)
• Provisioning them to end users is painful — you need to generate certs, distribute them securely, handle revocation
• They're rarely used for human-facing auth for exactly these reasons

Client certs work well for service-to-service auth (where both ends are automated), but for a browser-based tool where humans need access, they're a poor fit. I should have thought that through more carefully.

Better approach: Caddy + Let's Encrypt + token-based auth with asymmetric signatures

Let's Encrypt handles the server certificate (so the browser trusts the server). That's the easy part and Caddy does it automatically.

For client authentication without shared secrets, the practical options are:

1. JWT signed with an asymmetric key pair (e.g. Ed25519 or RS256): During provisioning, you install only the public key on the machine. Your browser app signs JWTs with the private key (which never leaves your app/infrastructure). Caddy verifies the JWT signature using the public key before proxying to ttyd. No secret passes through cloud-init.

2. OAuth2/OIDC: Caddy can validate tokens from an external identity provider (e.g. your own service, or something like Auth0). The machine only needs the provider's public JWKS endpoint URL — again, no secrets on the machine.

Option 1 is simpler and self-contained — no external IdP dependency. The flow would be:

Your app (has private key)
    │
    │  Signs a JWT
    ▼
Browser opens wss://machine.example.com/ws?token=<JWT>
    │
    ▼
Caddy (has public key, verifies JWT signature)
    │
    │  Valid → proxy to ttyd
    ▼
ttyd

During cloud-init you'd only provision: - The Ed25519/RSA public key (safe to expose) - Caddy config that references it

Does this approach work for your use case? If so I'll write the script using JWT verification with an asymmetric key pair, with Let's Encrypt for the server TLS.

Before I write the script, one design detail worth surfacing: Caddy doesn't include JWT verification natively. Building a custom Caddy binary with a plugin would require Go on the machine, which is heavy. Instead, the clean approach is:

• A ~25-line Python3 script using python3-jwt + python3-cryptography (apt packages, no pip) as a JWT verifier
• Caddy's forward_auth directive calls it on WebSocket requests only
• Static assets (xterm.js, CSS) are served unauthenticated — they're inert without a valid WebSocket connection

Browser  →  wss://host/ws?token=<JWT>
                │
            Caddy (Let's Encrypt TLS)
                │
            forward_auth → Python JWT verifier (localhost:9222)
                │              extracts token from X-Forwarded-Uri
                │              verifies signature with public key
                ▼
            reverse_proxy → ttyd (localhost:7681, runs bash as shell user)

Let me write it.

Here's what the script does:

Components installed: - ttyd (1.7.7 binary from GitHub) — C-based terminal server, ~500KB, serves xterm.js UI and WebSocket - Caddy (from official apt repo) — reverse proxy with automatic Let's Encrypt - python3-jwt + python3-cryptography (apt packages) — for the JWT verifier

Three systemd services: - ttyd.service — runs bash -l as the shell user, listens on localhost:7681 only - jwt-verify.service — 25-line Python script, listens on localhost:9222 - caddy — TLS termination, forward_auth on /ws path, reverse proxy to ttyd

Arguments: - --fqdn DOMAIN (required) — for Let's Encrypt cert - --jwt-public-key-file PATH (required) — PEM public key (Ed25519, RSA, or ECDSA) - --shell-user NAME (default: webshell) — user context for shell sessions - -f — force reinstall

Auth flow: Only the WebSocket path (/ws) requires JWT auth. The static UI assets (xterm.js, CSS) are served without auth since they're inert without a valid WebSocket connection. The token goes as a query parameter (?token=<JWT>) since the browser WebSocket API doesn't support custom headers.

Usage via combine.sh:

combine.sh \
  --script-url web-shell.sh \
  --script-args "--fqdn shell.example.com --jwt-public-key-file /path/to/public.pem"

A few things to consider:

1. Key generation (client side): openssl genpkey -algorithm ed25519 -out private.pem then openssl pkey -in private.pem -pubonly -out public.pem. Only public.pem goes to the machine.
2. JWT claims: The verifier currently just checks the signature and expiry (exp). We could add audience/issuer checks if you want tighter scoping.
3. Single session: As written, ttyd shares one shell session across connections. If you need per-connection sessions, ttyd supports --once (one-shot) or we could explore alternatives.

Want me to adjust anything — e.g. add claim validation, handle multi-session, or tweak the auth flow?

Good point — the Web Crypto API supports Ed25519 (in modern browsers) and RS256/ES256 broadly. A minimal example app would serve as both a test harness and reference implementation.

Let me think about what this needs:

1. Key generation — done in-browser via Web Crypto API
2. JWT signing — done in-browser (no server-side signing needed)
3. Interactive terminal — xterm.js connecting to the WebSocket
4. Programmatic command execution — demonstrating the "orchestration" use case

The example app should be a single HTML file (or small set of static files) that a developer can open locally or serve from anywhere — no build step, no server-side runtime.

Let me also think about the key provisioning workflow from the browser perspective:

1. User generates Ed25519 key pair in browser (Web Crypto)
2. Exports public key as PEM → provides it during machine provisioning
3. Private key stays in browser (localStorage or downloaded)
4. To connect: browser signs a JWT with private key, opens WebSocket with ?token=JWT

Let me build this out.

Here's what the example app provides:

Section 1 — Key Pair Management - Generate Ed25519 key pair entirely in-browser (Web Crypto API) - Export public key as PEM to copy/paste into machine provisioning - Save/load keys from localStorage for persistence across sessions

Section 2 — Connection - Enter the machine's FQDN, set JWT lifetime - JWT is signed client-side with the Ed25519 private key — no server needed

Section 3 — Interactive Terminal - xterm.js connected via wss://host/ws?token=JWT - Full terminal experience: handles stdin/stdout and resize events - Speaks ttyd's binary WebSocket protocol (type-byte prefixed messages)

Section 4 — Programmatic Command Execution - Opens a separate WebSocket connection per command - Wraps commands with random sentinel markers (echo __START__ / echo __END__ $?) - Sets TERM=dumb to suppress escape sequences - Extracts clean stdout and exit code between markers - Demonstrates the orchestration pattern for browser JS/TS code

To use it: just open index.html in a browser (or serve it with any static file server). No build step, no Node.js, no dependencies beyond xterm.js from CDN.

Browser requirements: Ed25519 Web Crypto needs Chrome 113+, Firefox 130+, or Safari 17+. The app shows a clear error if the browser doesn't support it.

The web-shell.js file also serves as a reference for how to integrate the WebSocket protocol into any application — the key functions are createJwt(), connectTerminal(), and execCommand().

Sounds good. A few notes that may help with testing:

• Quick local test of ttyd (before the full Caddy/JWT setup): you can run ttyd bash directly on the machine and hit http://localhost:7681 to verify the terminal works in isolation.
• Key provisioning: generate the key pair in the example app, copy the PEM from the text area, and save it to a file on the machine before running web-shell.sh --jwt-public-key-file /path/to/public.pem --fqdn ....
• DNS: Let's Encrypt needs the FQDN to resolve to the machine's IP before Caddy can issue a cert. If testing without DNS, you can temporarily configure Caddy with a self-signed cert instead.

Let me know what you find — happy to iterate on any of it.

Done. Here's what was created:

examples/web-shell/README.md covers: - Architecture diagram and component overview - Authentication flow explanation (why public key only, why query parameter for token) - Step-by-step setup: key generation → provisioning → connecting - Script argument reference - Interactive terminal usage - Programmatic command execution pattern with code examples - ttyd WebSocket protocol reference table - Security considerations - Browser requirements - Systemd service management and config file locations - Troubleshooting guide

README.md (project root) — added a web-shell.sh entry to the scripts list with a pointer to the detailed docs.