codebay 0.8.0 → 0.9.0

package/src/lib/devcontainer.server.ts

@@ -3,15 +3,18 @@ import { existsSync, statSync } from 'node:fs';
 import { basename, dirname, join, relative } from 'node:path';
 import { homedir } from 'node:os';
 import { INSTALL_SCRIPT as TMUX_INSTALL_SCRIPT } from '../container-injections/tmux.ts';
+import { INSTALL_SCRIPT as TTYD_INSTALL_SCRIPT } from '../container-injections/ttyd.ts';
 import { EXTENSION_ID as CLAUDE_CODE_EXTENSION_ID } from '../container-injections/claude-code-ide-extension.ts';
 import {
 	CODE_SERVER_PORT,
 	DEFAULT_IMAGE,
 	PUBLISH_HOST,
+	TTYD_PORT,
 	devcontainerBin,
 	dockerEnv
 } from './config.server.ts';
 import { spawnCapture } from './spawn.server.ts';
+import type { InstanceMode } from './db.server.ts';
 import type { PortForward } from '../types.ts';
 
 const CODE_SERVER_FEATURE = 'ghcr.io/coder/devcontainer-features/code-server:1';
@@ -49,11 +52,32 @@ const TMUX_FEATURE_INSTALL =
 	') || echo "codebay-tmux: install failed (non-fatal); the manager retries after the container starts"\n' +
 	'exit 0\n';
 
+/** Relative to .devcontainer/. Only written for terminal-mode instances. */
+const TTYD_FEATURE_DIR = 'codebay-ttyd';
+
+const TTYD_FEATURE_METADATA = {
+	id: 'codebay-ttyd',
+	version: '1.0.0',
+	name: 'ttyd (Codebay, best-effort)',
+	description:
+		'Installs ttyd at image build time so the terminal is reachable in a firewalled container. Never fails the build.'
+};
+
+/** Best-effort like tmux: build time is the only reliable moment to fetch in an egress-firewalled container. */
+const TTYD_FEATURE_INSTALL =
+	'#!/bin/sh\n' +
+	'(\n' +
+	`${TTYD_INSTALL_SCRIPT}\n` +
+	') || echo "codebay-ttyd: install failed (non-fatal); the manager retries after the container starts"\n' +
+	'exit 0\n';
+
 /** Manager-dropped files the project's own .gitignore won't cover, kept out of git status. */
 const MANAGER_GIT_EXCLUDES = [
 	'/.devcontainer/code-server-settings.json',
 	'/.devcontainer/devcontainer-lock.json',
 	'/.devcontainer/codebay-tmux/',
+	'/.devcontainer/codebay-ttyd/',
+	'/.devcontainer/codebay-terminal.sh',
 	'/.vscode/tasks.json'
 ];
 
@@ -86,6 +110,9 @@ const CODE_SERVER_SETTINGS = {
 
 const TMUX_SESSION = 'codebay';
 
+/** The split view's right-hand pane: a plain shell, kept apart from the Claude session. */
+const TMUX_SHELL_SESSION = 'codebay-shell';
+
 /** Written to `$HOME` when the post-up injection sequence finishes; the terminal launcher waits on it. */
 export const INJECTIONS_DONE_FILE = '.codebay-injections-done';
 
@@ -148,6 +175,52 @@ const CODE_SERVER_LAUNCH =
 	`nohup code-server --bind-addr 0.0.0.0:${CODE_SERVER_PORT} --auth none ` +
 	`--disable-workspace-trust \\"$PWD\\" >/tmp/code-server.log 2>&1 &"`;
 
+/** Staged next to the config; ttyd runs it as its command so the nested quoting stays in a real file. */
+const TTYD_LAUNCH_SCRIPT_FILE = 'codebay-terminal.sh';
+
+/** The one `?arg=` value ttyd is allowed to act on; anything else falls through to Claude. */
+export const TTYD_SHELL_ARG = 'shell';
+
+/**
+ * ttyd runs this per browser connection. `tmux -A` attaches to the shared `codebay` session
+ * (or creates it), so Claude survives reconnects. No WAIT_FOR_IDE_BRIDGE — terminal mode has
+ * no code-server extension host to race. Kept in a file so the tmux command's own quoting isn't
+ * nested inside the postStartCommand's shell quoting.
+ *
+ * `$1` comes from the URL's `?arg=` (ttyd's --url-arg), so it is untrusted — hence a literal
+ * compare and never an eval. The shell branch sits above the injections wait so the split view's
+ * scratch shell opens immediately instead of blocking on Claude's boot sentinel.
+ */
+const TTYD_LAUNCH_SCRIPT =
+	'#!/usr/bin/env bash\n' +
+	'export SHELL="${SHELL:-/bin/bash}"\n' +
+	`if [ "$1" = "${TTYD_SHELL_ARG}" ]; then\n` +
+	'  if command -v tmux >/dev/null 2>&1; then\n' +
+	`    exec tmux new-session -A -s ${TMUX_SHELL_SESSION}\n` +
+	'  fi\n' +
+	'  exec "$SHELL" -l\n' +
+	'fi\n' +
+	WAIT_FOR_INJECTIONS +
+	'\n' +
+	`if command -v tmux >/dev/null 2>&1; then\n` +
+	`  exec tmux new-session -A -s ${TMUX_SESSION} 'claude --dangerously-skip-permissions; exec "$SHELL" -l'\n` +
+	'fi\n' +
+	'claude --dangerously-skip-permissions\n' +
+	'exec "$SHELL" -l\n';
+
+// ttyd defaults to read-only, so --writable is required for keyboard input. Guarded by `pgrep -x`
+// (process name) so a folderOpen/rebuild can't stack a second daemon — never `pgrep -f`, whose
+// cmdline match also matches this very shell, which would skip the launch every time.
+const TTYD_LAUNCH =
+	`bash -c "` +
+	`export SHELL=\\"\${SHELL:-/bin/bash}\\"; ` +
+	`command -v ttyd >/dev/null 2>&1 || exit 0; ` +
+	`pgrep -x ttyd >/dev/null 2>&1 || ` +
+	// --url-arg forwards the connection URL's `?arg=` into the launcher's argv, so one ttyd serves
+	// both the Claude session and the split view's scratch shell (--writable is covered above).
+	`nohup ttyd --port ${TTYD_PORT} --writable --url-arg ` +
+	`bash \\"$PWD/.devcontainer/${TTYD_LAUNCH_SCRIPT_FILE}\\" >/tmp/ttyd.log 2>&1 &"`;
+
 export async function devcontainerCliAvailable(): Promise<boolean> {
 	return (await spawnCapture([devcontainerBin(), '--version'])) !== null;
 }
@@ -288,7 +361,15 @@ export async function readDeclaredContainerPorts(workspaceDir: string): Promise<
 	const ports = new Set<number>();
 	for (const entry of entries) {
 		const port = containerPortOf(entry);
-		if (Number.isInteger(port) && port > 0 && port <= 65535 && port !== CODE_SERVER_PORT) {
+		// Both reserved internal ports are excluded regardless of mode, so neither can be
+		// double-mapped when writeOverrideConfig renders its own appPort entry for it.
+		if (
+			Number.isInteger(port) &&
+			port > 0 &&
+			port <= 65535 &&
+			port !== CODE_SERVER_PORT &&
+			port !== TTYD_PORT
+		) {
 			ports.add(port);
 		}
 	}
@@ -303,8 +384,10 @@ export async function writeOverrideConfig(
 	workspaceDir: string,
 	hostPort: number,
 	forwards: PortForward[] = [],
-	defaultImage: string = DEFAULT_IMAGE
+	defaultImage: string = DEFAULT_IMAGE,
+	mode: InstanceMode = 'ide'
 ): Promise<{ imageSource: string }> {
+	const isTerminal = mode === 'terminal';
 	const target = configPath(workspaceDir);
 	let config: DevcontainerConfig = {};
 
@@ -326,23 +409,30 @@ export async function writeOverrideConfig(
 	}
 
 	// A local feature is addressed relative to the config, which sits at one of two depths.
-	const tmuxFeatureKey = `./${relative(dirname(target), join(workspaceDir, '.devcontainer', TMUX_FEATURE_DIR))}`;
+	const featureKey = (dir: string) =>
+		`./${relative(dirname(target), join(workspaceDir, '.devcontainer', dir))}`;
+	const tmuxFeatureKey = featureKey(TMUX_FEATURE_DIR);
+	const ttydFeatureKey = featureKey(TTYD_FEATURE_DIR);
 
-	// Node/Claude/gh only for the default image — projects with their own config own their tooling.
+	// Terminal mode swaps code-server for ttyd; otherwise (tmux, tooling) the two are identical.
+	// Node/Claude/gh: always in terminal mode (its launcher *is* `claude`), else only the default image.
 	config.features = {
 		...(config.features ?? {}),
-		[CODE_SERVER_FEATURE]: { host: '0.0.0.0', port: CODE_SERVER_PORT, auth: 'none' },
+		...(isTerminal
+			? { [ttydFeatureKey]: {} }
+			: { [CODE_SERVER_FEATURE]: { host: '0.0.0.0', port: CODE_SERVER_PORT, auth: 'none' } }),
 		[tmuxFeatureKey]: {},
-		...(hadConfig
-			? {}
-			: { [NODE_FEATURE]: {}, [CLAUDE_CODE_FEATURE]: {}, [GITHUB_CLI_FEATURE]: {} })
+		...(isTerminal || !hadConfig
+			? { [NODE_FEATURE]: {}, [CLAUDE_CODE_FEATURE]: {}, [GITHUB_CLI_FEATURE]: {} }
+			: {})
 	};
 
+	const servedPort = isTerminal ? TTYD_PORT : CODE_SERVER_PORT;
 	// Rendered from scratch rather than merged, so removing a forward actually drops its mapping.
-	// code-server stays loopback even under HOST=0.0.0.0 — it has no auth of its own, so the LAN
-	// reaches it only through the Basic-Auth-gated /p/:id/ proxy.
+	// The served port stays loopback even under HOST=0.0.0.0 — neither code-server nor ttyd has
+	// auth of its own, so the LAN reaches it only through the Basic-Auth-gated /p/:id/ proxy.
 	config.appPort = [
-		`127.0.0.1:${hostPort}:${CODE_SERVER_PORT}`,
+		`127.0.0.1:${hostPort}:${servedPort}`,
 		...forwards.map((f) => `${PUBLISH_HOST}:${f.host_port}:${f.container_port}`)
 	];
 
@@ -351,26 +441,30 @@ export async function writeOverrideConfig(
 	runArgs.add(HOST_GATEWAY_ARG);
 	config.runArgs = [...runArgs];
 
+	const launch = isTerminal ? TTYD_LAUNCH : CODE_SERVER_LAUNCH;
 	const existing = config.postStartCommand;
 	config.postStartCommand =
-		typeof existing === 'string' && existing.trim()
-			? `${existing} && ${CODE_SERVER_LAUNCH}`
-			: CODE_SERVER_LAUNCH;
+		typeof existing === 'string' && existing.trim() ? `${existing} && ${launch}` : launch;
 
 	await mkdir(join(workspaceDir, '.devcontainer'), { recursive: true }).catch(() => {});
 	await writeFile(target, JSON.stringify(config, null, 2) + '\n', 'utf8');
 
-	// Staged next to the config; CODE_SERVER_LAUNCH copies it into the user-data dir on first start.
-	await writeFile(
-		join(workspaceDir, '.devcontainer', CODE_SERVER_SETTINGS_FILE),
-		JSON.stringify(CODE_SERVER_SETTINGS, null, 2) + '\n',
-		'utf8'
-	);
+	if (isTerminal) {
+		await writeTtydFeature(workspaceDir);
+		await writeTerminalLaunchScript(workspaceDir);
+	} else {
+		// Staged next to the config; CODE_SERVER_LAUNCH copies it into the user-data dir on first start.
+		await writeFile(
+			join(workspaceDir, '.devcontainer', CODE_SERVER_SETTINGS_FILE),
+			JSON.stringify(CODE_SERVER_SETTINGS, null, 2) + '\n',
+			'utf8'
+		);
+		// The VS Code Terminal task is code-server-only; ttyd runs its own launcher script instead.
+		await writeTerminalTask(workspaceDir);
+	}
 
 	await writeTmuxFeature(workspaceDir);
 
-	await writeTerminalTask(workspaceDir);
-
 	await writeLocalGitExclude(workspaceDir);
 
 	return { imageSource };
@@ -460,6 +554,26 @@ async function writeTmuxFeature(workspaceDir: string): Promise<void> {
 	await chmod(installPath, 0o755);
 }
 
+async function writeTtydFeature(workspaceDir: string): Promise<void> {
+	const dir = join(workspaceDir, '.devcontainer', TTYD_FEATURE_DIR);
+	await mkdir(dir, { recursive: true }).catch(() => {});
+	await writeFile(
+		join(dir, 'devcontainer-feature.json'),
+		JSON.stringify(TTYD_FEATURE_METADATA, null, 2) + '\n',
+		'utf8'
+	);
+	const installPath = join(dir, 'install.sh');
+	await writeFile(installPath, TTYD_FEATURE_INSTALL, 'utf8');
+	await chmod(installPath, 0o755);
+}
+
+/** Staged next to the config; TTYD_LAUNCH runs it as ttyd's command. */
+async function writeTerminalLaunchScript(workspaceDir: string): Promise<void> {
+	const path = join(workspaceDir, '.devcontainer', TTYD_LAUNCH_SCRIPT_FILE);
+	await writeFile(path, TTYD_LAUNCH_SCRIPT, 'utf8');
+	await chmod(path, 0o755);
+}
+
 /** Replaces the managed task rather than skipping it, so a rebuild picks up command changes. */
 async function writeTerminalTask(workspaceDir: string): Promise<void> {
 	const tasksPath = join(workspaceDir, '.vscode', 'tasks.json');

package/src/lib/health.server.ts

@@ -41,7 +41,7 @@ async function check(row: InstanceRow): Promise<InstanceHealth> {
 		codeServerAccessible(row.host_port),
 		publishedContainerPorts(row.container_id),
 		Promise.all(
-			resolveInjections()
+			resolveInjections(row.mode)
 				.filter((i) => i.check)
 				.map(async (i) => ({
 					id: i.id,

package/src/lib/injections.server.ts

@@ -1,8 +1,9 @@
-import type { InstanceRow } from './db.server.ts';
+import type { InstanceMode, InstanceRow } from './db.server.ts';
 import type { ExecTarget } from './exec.server.ts';
 import { getOption } from './db.server.ts';
 import { gitSafeDirectory } from '../container-injections/git-safe-directory.ts';
 import { tmux } from '../container-injections/tmux.ts';
+import { ttyd } from '../container-injections/ttyd.ts';
 import { gitIdentity } from '../container-injections/git-identity.ts';
 import { claudeCodeCredentials } from '../container-injections/claude-code-credentials.ts';
 import { claudeCodeCustom } from '../container-injections/claude-code-custom.ts';
@@ -32,6 +33,8 @@ export interface Injection {
 	/** Doubles as the health-row key. */
 	id: string;
 	label: string;
+	/** Restrict to specific instance modes; absent means it applies to every mode. */
+	modes?: InstanceMode[];
 	/** Omit for injections with no host dependency — presence is what draws the setup-UI chip. */
 	auth?: {
 		/** Short instruction shown when unavailable, e.g. "run `gh auth login`". */
@@ -49,6 +52,8 @@ const BASE_INJECTIONS_HEAD: Injection[] = [
 	gitSafeDirectory,
 	// The package install is the slowest injection, so start it before a folderOpen can find tmux missing.
 	tmux,
+	// Terminal-mode only (filtered by resolveInjections); a download, so run it early like tmux.
+	ttyd,
 	gitIdentity
 ];
 
@@ -69,14 +74,19 @@ const BASE_INJECTIONS_TAIL: Injection[] = [
 	hostEnvVars
 ];
 
-/** Resolved per call so toggling the custom-endpoint setting takes effect without a restart. */
-export function resolveInjections(): Injection[] {
+/**
+ * Resolved per call so toggling the custom-endpoint setting takes effect without a restart.
+ * `mode` drops injections that don't apply to it (e.g. ttyd off IDE instances, the IDE
+ * extension off terminal ones); omit it in mode-agnostic contexts to keep every injection.
+ */
+export function resolveInjections(mode?: InstanceMode): Injection[] {
 	const claudeInjection =
 		getOption('custom_endpoint_enabled') === '1' ? claudeCodeCustom : claudeCodeCredentials;
-	return [...BASE_INJECTIONS_HEAD, claudeInjection, ...BASE_INJECTIONS_TAIL];
+	const all = [...BASE_INJECTIONS_HEAD, claudeInjection, ...BASE_INJECTIONS_TAIL];
+	return mode ? all.filter((i) => !i.modes || i.modes.includes(mode)) : all;
 }
 
-/** @deprecated Use `resolveInjections()`; this ignores settings and is kept for the tests. */
+/** @deprecated Use `resolveInjections()`; this ignores settings/mode and is kept for the tests. */
 export const injections: Injection[] = [
 	...BASE_INJECTIONS_HEAD,
 	claudeCodeCredentials,

package/src/lib/instances.server.ts

@@ -6,7 +6,8 @@ import {
 	DEFAULT_COPY_IGNORE,
 	DEFAULT_IMAGE,
 	INSTANCES_DIR,
-	parseCopyIgnore
+	parseCopyIgnore,
+	TTYD_PORT
 } from './config.server.ts';
 import {
 	allForwards,
@@ -23,6 +24,7 @@ import {
 	recordFolder,
 	updateInstance,
 	usedPorts,
+	type InstanceMode,
 	type InstanceRow,
 	type InstanceStatus
 } from './db.server.ts';
@@ -51,7 +53,13 @@ import { isRepoUrl, parseRepoUrl } from './repo-url.ts';
 import { currentHealthSnapshots, stopHealthMonitor, syncHealthMonitors } from './health.server.ts';
 import { pickFreePort } from './ports.server.ts';
 import type { ServerWebSocket } from 'bun';
-import type { Instance, InstanceHealth } from '../types.ts';
+import {
+	isInstanceFilter,
+	normalizeMode,
+	type Instance,
+	type InstanceFilter,
+	type InstanceHealth
+} from '../types.ts';
 
 /**
  * `bridge_token` authenticates the no-Basic-Auth `/api/bridge/` endpoint, so it
@@ -108,7 +116,11 @@ export type StreamEvent =
 	| { type: 'health'; data: { id: string; health: InstanceHealth } }
 	| { type: 'preflight'; data: { docker: boolean; cli: boolean } }
 	// `name` is the chosen sprite, or null for the default box logo. Lets the header swap live.
-	| { type: 'pet'; data: { name: string | null } };
+	| { type: 'pet'; data: { name: string | null } }
+	// The dashboard run-state filter, so a change in one tab propagates to every open client.
+	| { type: 'filter'; data: { value: InstanceFilter } }
+	// The global default editor surface, so the picker's toggle follows a settings change.
+	| { type: 'default-mode'; data: { mode: InstanceMode } };
 
 interface StreamHub {
 	sockets: Set<ServerWebSocket<unknown>>;
@@ -159,6 +171,16 @@ export function broadcastPet(name: string | null): void {
 	broadcast({ type: 'pet', data: { name } });
 }
 
+/** Called when the filter changes so every open dashboard reflects it without a reload. */
+export function broadcastFilter(value: InstanceFilter): void {
+	broadcast({ type: 'filter', data: { value } });
+}
+
+/** Settings opens in its own popup, so the dashboard behind it needs the new default pushed. */
+export function broadcastDefaultMode(mode: InstanceMode): void {
+	broadcast({ type: 'default-mode', data: { mode } });
+}
+
 async function reconcileInstances(force = false): Promise<void> {
 	const list = await listInstances();
 	const listJson = JSON.stringify(list);
@@ -200,6 +222,14 @@ export function streamOpen(ws: ServerWebSocket<unknown>): void {
 	void backgroundPreflight().then((pf) => sendTo(ws, { type: 'preflight', data: pf }));
 	// Keeps a reconnecting client correct even if the pet changed while it was away.
 	sendTo(ws, { type: 'pet', data: { name: getOption('pet') || null } });
+	// Same, for the filter, so a client that reconnects picks up a change made while it was away.
+	const savedFilter = getOption('instance_filter');
+	sendTo(ws, {
+		type: 'filter',
+		data: { value: isInstanceFilter(savedFilter) ? savedFilter : 'all' }
+	});
+	// Same, for the default mode the picker's toggle seeds from.
+	sendTo(ws, { type: 'default-mode', data: { mode: getDefaultMode() } });
 }
 
 export function streamClose(ws: ServerWebSocket<unknown>): void {
@@ -291,13 +321,15 @@ async function provision(row: InstanceRow, opts: { noCache?: boolean } = {}): Pr
 			container_port: f.container_port,
 			host_port: f.host_port
 		}));
-		appendLog(row.id, `Injecting code-server (host port ${row.host_port})\n`);
+		const surface = row.mode === 'terminal' ? 'ttyd terminal' : 'code-server';
+		appendLog(row.id, `Injecting ${surface} (host port ${row.host_port})\n`);
 		const defaultImage = getOption('default_image') ?? DEFAULT_IMAGE;
 		const { imageSource } = await writeOverrideConfig(
 			row.workspace_path,
 			row.host_port,
 			forwards,
-			defaultImage
+			defaultImage,
+			row.mode
 		);
 		updateInstance(row.id, { image_source: imageSource });
 
@@ -336,7 +368,7 @@ async function provision(row: InstanceRow, opts: { noCache?: boolean } = {}): Pr
 			instance: row
 		};
 		// Swallow per-injection failures so one bad injection can't abort the rest of provisioning.
-		for (const injection of resolveInjections()) {
+		for (const injection of resolveInjections(row.mode)) {
 			try {
 				await injection.apply(target, (msg) => appendLog(row.id, msg));
 			} catch (err) {
@@ -370,11 +402,16 @@ function uniqueName(desired: string, excludeId?: string): string {
 	}
 }
 
+/** The global fallback the picker's mode toggle starts on; a per-instance choice overrides it. */
+export function getDefaultMode(): InstanceMode {
+	return normalizeMode(getOption('default_mode'));
+}
+
 /** `source` is either a local folder (copied) or a Git URL (cloned); boot runs in the background. */
 export async function createInstance(
 	source: string,
 	name?: string,
-	opts: { branch?: string } = {}
+	opts: { branch?: string; mode?: InstanceMode } = {}
 ): Promise<InstanceRow> {
 	const parsedRepo = parseRepoUrl(source);
 	if (parsedRepo) {
@@ -399,7 +436,9 @@ export async function createInstance(
 		created_at: Date.now(),
 		bridge_token: crypto.randomUUID().replace(/-/g, ''),
 		remote_user: null,
-		image_source: null
+		image_source: null,
+		mode: opts.mode ?? getDefaultMode(),
+		terminal_split: 0
 	};
 	insertInstance(row);
 	// Strip the de-dup `#2` suffix so the recent-folders list keeps the base name.
@@ -455,6 +494,18 @@ export async function listInstances(): Promise<Instance[]> {
 	}));
 }
 
+/**
+ * Remembers whether the terminal's scratch-shell pane was left open. Deliberately skips
+ * `triggerReconcile()` — it's a per-instance UI preference read once at page load, so pushing the
+ * whole instance list to every socket on each toggle would be pure noise.
+ */
+export function setTerminalSplit(id: string, open: boolean): InstanceRow {
+	const row = getInstance(id);
+	if (!row) throw new Error('Instance not found');
+	updateInstance(id, { terminal_split: open ? 1 : 0 });
+	return getInstance(id)!;
+}
+
 export function renameInstance(id: string, name: string): InstanceRow {
 	const row = getInstance(id);
 	if (!row) throw new Error('Instance not found');
@@ -473,8 +524,11 @@ export async function addForwardedPort(id: string, containerPort: number): Promi
 	if (!Number.isInteger(containerPort) || containerPort < 1 || containerPort > 65535) {
 		throw new Error('Port must be an integer between 1 and 65535');
 	}
-	if (containerPort === CODE_SERVER_PORT) {
-		throw new Error(`Port ${CODE_SERVER_PORT} is reserved for code-server`);
+	const reserved = row.mode === 'terminal' ? TTYD_PORT : CODE_SERVER_PORT;
+	if (containerPort === reserved) {
+		throw new Error(
+			`Port ${reserved} is reserved for ${row.mode === 'terminal' ? 'the terminal' : 'code-server'}`
+		);
 	}
 	if (listForwards(id).some((f) => f.container_port === containerPort)) {
 		throw new Error(`Port ${containerPort} is already forwarded`);

package/src/lib/proxy.server.ts

@@ -50,6 +50,25 @@ interface RelayState {
 	client?: WebSocket;
 	/** Frames received from the browser before the upstream socket is open. */
 	pending: Frame[];
+	/** Frames the upstream sent before the browser socket existed (connect-first path only). */
+	inbound?: Frame[];
+	/** The client's requested subprotocols, forwarded upstream — ttyd requires its `tty` one. */
+	subprotocols?: string[];
+}
+
+/** Opens the upstream socket and buffers anything it emits until the browser socket is wired up. */
+function connectUpstream(
+	url: string,
+	subprotocols: string[]
+): Promise<{ client: WebSocket; inbound: Frame[] }> {
+	return new Promise((resolve, reject) => {
+		const client = new WebSocket(url, subprotocols);
+		client.binaryType = 'arraybuffer';
+		const inbound: Frame[] = [];
+		client.onmessage = (e) => inbound.push(e.data as Frame);
+		client.onopen = () => resolve({ client, inbound });
+		client.onerror = () => reject(new Error('upstream websocket error'));
+	});
 }
 
 async function proxyHttp(event: MochiApiEvent, port: number, rest: string): Promise<Response> {
@@ -91,20 +110,53 @@ async function proxyHttp(event: MochiApiEvent, port: number, rest: string): Prom
 	});
 }
 
-function proxyUpgrade(event: MochiApiEvent, port: number, rest: string): Response {
+async function proxyUpgrade(event: MochiApiEvent, port: number, rest: string): Promise<Response> {
+	const requested = event.request.headers.get('sec-websocket-protocol');
+	const subprotocols = requested
+		? requested
+				.split(',')
+				.map((s) => s.trim())
+				.filter(Boolean)
+		: undefined;
+	const upstreamWsUrl = `ws://127.0.0.1:${port}${rest}${event.url.search}`;
+
+	const state: RelayState = { upstreamWsUrl, pending: [], subprotocols };
+	let selected: string | undefined;
+
+	// When subprotocols are in play, open the upstream first so the 101 echoes the one it actually
+	// negotiated instead of guessing its first offer — a mismatch would leave the browser and
+	// upstream disagreeing on the protocol. code-server offers none and connects lazily in open().
+	if (subprotocols) {
+		try {
+			const { client, inbound } = await connectUpstream(upstreamWsUrl, subprotocols);
+			state.client = client;
+			state.inbound = inbound;
+			selected = client.protocol || undefined;
+		} catch {
+			return new Response('Upstream WebSocket unreachable', { status: 502 });
+		}
+	}
+
 	const data: MochiWsData<RelayState> = {
 		__mochiRoutePattern: PROXY_WS_PATTERN,
 		__mochiOpenedAt: performance.now(),
 		__mochiPath: event.url.pathname,
-		user: { upstreamWsUrl: `ws://127.0.0.1:${port}${rest}${event.url.search}`, pending: [] }
+		user: state
 	};
+	const headers = selected ? { 'Sec-WebSocket-Protocol': selected } : undefined;
 	// Bun's Server is typed with a fixed WebSocketData; Mochi casts the same way for its own upgrades.
 	const ok = (
 		event.server as unknown as {
-			upgrade: (req: Request, opts: { data: MochiWsData<RelayState> }) => boolean;
+			upgrade: (
+				req: Request,
+				opts: { data: MochiWsData<RelayState>; headers?: Record<string, string> }
+			) => boolean;
 		}
-	).upgrade(event.request, { data });
-	if (!ok) return new Response('WebSocket upgrade failed', { status: 426 });
+	).upgrade(event.request, { data, headers });
+	if (!ok) {
+		if (state.client) safeClose(state.client, 1000, ''); // don't orphan the pre-opened upstream
+		return new Response('WebSocket upgrade failed', { status: 426 });
+	}
 	// Bun already sent the real 101; this is ignored, but Mochi's resolve chain reads a status.
 	return new Response(null, { status: 101 });
 }
@@ -127,7 +179,7 @@ export const proxyRoutes: Record<string, MochiRouteValue> = {
 
 		// An upgrade is a GET carrying `Upgrade: websocket`, so Bun routes it here too.
 		if (event.request.headers.get('upgrade')?.toLowerCase() === 'websocket') {
-			return proxyUpgrade(event, port, rest);
+			return await proxyUpgrade(event, port, rest);
 		}
 		return proxyHttp(event, port, rest);
 	}),
@@ -137,14 +189,27 @@ export const proxyRoutes: Record<string, MochiRouteValue> = {
 		upgrade: () => false,
 		open(ws: ServerWebSocket<MochiWsData<RelayState>>) {
 			const state = ws.data.user;
-			const client = new WebSocket(state.upstreamWsUrl);
+			// Pre-opened during the handshake when a subprotocol was negotiated; otherwise connect now.
+			const client =
+				state.client ??
+				(state.subprotocols
+					? new WebSocket(state.upstreamWsUrl, state.subprotocols)
+					: new WebSocket(state.upstreamWsUrl));
 			client.binaryType = 'arraybuffer';
 			state.client = client;
 
-			client.onopen = () => {
-				for (const frame of state.pending) sendFrame(client, frame);
-				state.pending = [];
-			};
+			// Drain whatever the upstream sent before this socket existed (connect-first path only).
+			if (state.inbound) {
+				for (const frame of state.inbound) {
+					try {
+						ws.send(frame as never);
+					} catch {
+						/* browser socket closed */
+					}
+				}
+				state.inbound = undefined;
+			}
+
 			client.onmessage = (e) => {
 				try {
 					ws.send(e.data);
@@ -154,6 +219,17 @@ export const proxyRoutes: Record<string, MochiRouteValue> = {
 			};
 			client.onclose = (e) => safeClose(ws, e.code, e.reason);
 			client.onerror = () => safeClose(ws, 1011, 'upstream error');
+
+			// A pre-opened socket already fired `onopen`, so flush now; a lazy one flushes on open.
+			if (client.readyState === WebSocket.OPEN) {
+				for (const frame of state.pending) sendFrame(client, frame);
+				state.pending = [];
+			} else {
+				client.onopen = () => {
+					for (const frame of state.pending) sendFrame(client, frame);
+					state.pending = [];
+				};
+			}
 		},
 		message(ws: ServerWebSocket<MochiWsData<RelayState>>, message) {
 			const state = ws.data.user;

package/src/pages/App.svelte

@@ -2,20 +2,22 @@
 	import '@fontsource-variable/doto';
 	import '@fontsource-variable/jetbrains-mono';
 	import AppShell from '../components/AppShell.svelte';
-	import type { Instance, Preflight } from '../types.ts';
+	import type { Instance, InstanceFilter, Preflight } from '../types.ts';
 	import type { AvatarArt } from '../avatars/index.ts';
 
 	let {
 		preflight,
 		initialPath,
 		snapshot,
-		pet
+		pet,
+		filter
 	}: {
 		preflight: Preflight;
 		initialPath: string;
 		snapshot: Instance[];
 		pet?: AvatarArt;
+		filter: InstanceFilter;
 	} = $props();
 </script>
 
-<AppShell {preflight} {initialPath} {snapshot} {pet} mochi:hydrate />
+<AppShell {preflight} {initialPath} {snapshot} {pet} {filter} mochi:hydrate />

package/src/pages/Settings.svelte

@@ -3,9 +3,11 @@
 	import '@fontsource-variable/jetbrains-mono';
 	import SettingsView from '../components/SettingsView.svelte';
 	import type { AvatarArt } from '../avatars/index.ts';
+	import type { InstanceMode } from '../types.ts';
 
 	let {
 		pet,
+		defaultMode,
 		defaultImage,
 		builtinImage,
 		disableBuildCache,
@@ -38,6 +40,7 @@
 		version
 	}: {
 		pet?: AvatarArt;
+		defaultMode: InstanceMode;
 		defaultImage: string;
 		builtinImage: string;
 		disableBuildCache: boolean;
@@ -73,6 +76,7 @@
 
 <SettingsView
 	{pet}
+	{defaultMode}
 	{defaultImage}
 	{builtinImage}
 	{disableBuildCache}