fix(cli): scaffold portable configs and support base paths

Generate plain default-exported configs so global installs do not depend on
resolving remobi from the project directory.

Add --base-path for prefixed deployments and thread it through the browser,
PWA assets, manifest URLs, and server routes.

Author: connorads

README.md

@@ -68,7 +68,7 @@ See [Mobile-friendly tmux config](.agents/skills/remobi-setup/references/mobile-
 
 For local development, see the [Development](#development) section below.
 
-Open `http://localhost:7681` on the same machine to verify it works. For phone access, put a trusted proxy/tunnel in front of it, for example [Tailscale Serve](.agents/skills/remobi-setup/references/tailscale-serve.md).
+Open `http://localhost:7681` on the same machine to verify it works. For phone access, put a trusted proxy/tunnel in front of it, for example [Tailscale Serve](.agents/skills/remobi-setup/references/tailscale-serve.md). If your proxy mounts remobi under a URL prefix, start remobi with `--base-path /that-prefix` so the HTML, PWA links, and WebSocket all use the same external path.
 
 ## Release channels
 
@@ -117,10 +117,11 @@ To report a vulnerability, see [SECURITY.md](SECURITY.md).
 ## CLI reference
 
 ```text
-remobi serve [--config <path>] [--port <n>] [--host <addr>] [-- <command...>]
+remobi serve [--config <path>] [--port <n>] [--host <addr>] [--base-path <path>] [-- <command...>]
   Start remobi with its built-in web terminal and PWA support.
   Default host: 127.0.0.1. Default port: 7681. Default command: tmux new-session -A -s main
   Example: remobi serve --host 0.0.0.0 --port 8080
+  Example: remobi serve --base-path /random-token
   Example: remobi serve --port 8080 -- tmux new -As dev
 
 remobi build [--config <path>] [--output <path>] [--dry-run]
@@ -150,9 +151,7 @@ When `--config` is not specified, remobi searches:
 Create `remobi.config.ts` (or run `remobi init`):
 
 ```typescript
-import { defineConfig } from 'remobi/config'
-
-export default defineConfig({
+export default {
   font: {
     family: 'JetBrainsMono NFM, monospace',
     mobileSizeDefault: 16,
@@ -208,10 +207,10 @@ export default defineConfig({
       ],
     },
   ],
-})
+}
 ```
 
-All fields are optional — defaults are filled in via `defineConfig()`.
+All fields are optional — the CLI fills in defaults internally when it loads the config.
 
 Shipped tmux drawer defaults stick to stock tmux bindings (`c`, `%`, `"`, `s`, `w`, `[`, `?`, `x`, `z`) rather than personal popup workflows.
 

build.ts

@@ -50,11 +50,12 @@ function readPrebuiltAsset(filename: string): string | null {
 export async function bundleClientAssets(
 	config: RemobiConfig,
 	version: string,
+	basePath = '/',
 ): Promise<{ js: string; css: string }> {
 	const prebuiltJs = readPrebuiltAsset('client.iife.js')
 	const prebuiltCss = readPrebuiltAsset('client.css')
 	if (prebuiltJs !== null && prebuiltCss !== null) {
-		const js = `globalThis.__remobiVersion=${JSON.stringify(version)};globalThis.__remobiConfig=${JSON.stringify(config)};${prebuiltJs}`
+		const js = `globalThis.__remobiVersion=${JSON.stringify(version)};globalThis.__remobiConfig=${JSON.stringify(config)};globalThis.__remobiBasePath=${JSON.stringify(basePath)};${prebuiltJs}`
 		return { js, css: prebuiltCss }
 	}
 
@@ -78,7 +79,7 @@ export async function bundleClientAssets(
 		throw new Error('remobi client build produced incomplete output')
 	}
 
-	const js = `globalThis.__remobiVersion=${JSON.stringify(version)};globalThis.__remobiConfig=${JSON.stringify(config)};${jsOutput.text}`
+	const js = `globalThis.__remobiVersion=${JSON.stringify(version)};globalThis.__remobiConfig=${JSON.stringify(config)};globalThis.__remobiBasePath=${JSON.stringify(basePath)};${jsOutput.text}`
 	return { js, css: cssOutput.text }
 }
 
@@ -87,10 +88,14 @@ export function renderClientHtml(
 	css: string,
 	config: RemobiConfig,
 	scriptNonce: string,
+	basePath = '/',
 ): string {
 	const viewport =
 		'<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1, viewport-fit=cover">'
-	const pwaHtml = config.pwa.enabled ? `${generatePwaHtml(config.name, config.pwa)}\n` : ''
+	const pwaHtml = config.pwa.enabled
+		? `${generatePwaHtml(config.name, config.pwa, basePath)}
+`
+		: ''
 	const fontLink = `<link rel="stylesheet" href="${escapeAttr(config.font.cdnUrl)}">`
 	const safeJs = js.replace(/<(?=\/script)/gi, '\\x3c')
 

cli.ts

@@ -57,7 +57,7 @@ function usage(): void {
 	console.log(`remobi v${VERSION} — mobile terminal overlay for tmux
 
 Usage:
-  remobi serve [--config <path>] [--port <n>] [--host <addr>] [--no-sleep] [-- <command...>]
+  remobi serve [--config <path>] [--port <n>] [--host <addr>] [--base-path <path>] [--no-sleep] [-- <command...>]
     Start remobi with a built-in web terminal, PWA support, and the configured command.
     Default host: 127.0.0.1. Default port: 7681. Default command: tmux new-session -A -s main
 
@@ -81,13 +81,15 @@ Flags:
   -o, --output <path>  Deprecated build output path flag
   -p, --port <n>       Port to serve on (serve only, default 7681)
       --host <addr>    Host/interface to bind (serve only, default 127.0.0.1)
+      --base-path <p>  Mount remobi under a URL prefix such as /random-token
   -n, --dry-run        Deprecated build/inject dry-run flag
       --no-sleep       Prevent macOS sleep while serving (caffeinate -s, serve only)
 
 Examples:
   remobi serve
   remobi serve --no-sleep
   remobi serve --host 0.0.0.0 --port 8080
+  remobi serve --base-path /random-token
   remobi serve --port 8080 -- tmux new -As dev`)
 }
 
@@ -225,7 +227,7 @@ async function main(): Promise<void> {
 		process.exit(1)
 	}
 
-	const { command, configPath, port, host, noSleep, command_ } = parsed.value
+	const { command, configPath, port, host, basePath, noSleep, command_ } = parsed.value
 
 	switch (command) {
 		case 'serve': {
@@ -237,6 +239,7 @@ async function main(): Promise<void> {
 				noSleep,
 				host,
 				VERSION,
+				basePath,
 			)
 			break
 		}
@@ -255,9 +258,7 @@ async function main(): Promise<void> {
 				console.error('remobi.config.ts already exists')
 				process.exit(1)
 			}
-			const template = `import { defineConfig } from 'remobi'
-
-export default defineConfig({
+			const template = `export default {
   // name: 'remobi',              // app name (tab title, PWA home screen label)
   // theme: 'catppuccin-mocha',
   // font: {
@@ -314,7 +315,7 @@ export default defineConfig({
   // reconnect: {
   //   enabled: true,              // show overlay + auto-reload on connection loss (default true)
   // },
-})
+}
 `
 			writeFileSync(targetPath, template)
 			console.log(`Created: ${targetPath}`)

src/base-path.ts

@@ -0,0 +1,36 @@
+export function normalizeBasePath(value: string): string | null {
+	if (value.length === 0 || !value.startsWith('/')) {
+		return null
+	}
+
+	if (value.includes('?') || value.includes('#')) {
+		return null
+	}
+
+	if (value === '/') {
+		return '/'
+	}
+
+	const trimmed = value.replace(/\/+$/g, '')
+	if (trimmed.length === 0 || trimmed === '/') {
+		return '/'
+	}
+
+	return trimmed
+}
+
+export function joinBasePath(basePath: string, path: string): string {
+	if (basePath === '/') {
+		return path
+	}
+
+	if (path === '/') {
+		return `${basePath}/`
+	}
+
+	return `${basePath}${path}`
+}
+
+export function documentRoute(basePath: string): string {
+	return basePath === '/' ? '/' : `${basePath}/`
+}

src/cli/args.ts

@@ -1,3 +1,5 @@
+import { normalizeBasePath } from '../base-path'
+
 type CliCommand = 'build' | 'inject' | 'init' | 'serve' | 'help' | 'version'
 
 interface ParsedCliArgs {
@@ -7,6 +9,7 @@ interface ParsedCliArgs {
 	readonly dryRun: boolean
 	readonly port?: number
 	readonly host?: string
+	readonly basePath?: string
 	readonly noSleep: boolean
 	readonly command_: readonly string[]
 }
@@ -29,6 +32,7 @@ interface ParseState {
 	dryRun: boolean
 	port?: number
 	host?: string
+	basePath?: string
 	noSleep: boolean
 }
 
@@ -101,6 +105,19 @@ const flagDefs: readonly FlagDef[] = [
 			return undefined
 		},
 	},
+	{
+		names: ['--base-path'],
+		validCommands: ['serve'],
+		takesValue: true,
+		apply(value, state) {
+			const normalized = normalizeBasePath(value ?? '')
+			if (normalized === null) {
+				return `Invalid base path: ${value}`
+			}
+			state.basePath = normalized
+			return undefined
+		},
+	},
 	{
 		names: ['--no-sleep'],
 		validCommands: ['serve'],
@@ -212,6 +229,7 @@ export function parseCliArgs(args: readonly string[]): ParseCliResult {
 			dryRun: state.dryRun,
 			port: state.port,
 			host: state.host,
+			basePath: state.basePath,
 			noSleep: state.noSleep,
 			command_: trailingCommand,
 		},

src/client-entry.ts

@@ -4,6 +4,7 @@ import { WebLinksAddon } from '@xterm/addon-web-links'
 import { Terminal } from '@xterm/xterm'
 import '@xterm/xterm/css/xterm.css'
 import '../styles/base.css'
+import { joinBasePath } from './base-path'
 import { createHookRegistry, init } from './index'
 import { parseServerMessage, serialiseClientMessage } from './session-protocol'
 import type { ClientMessage } from './session-protocol'
@@ -13,10 +14,12 @@ import { onTap } from './util/tap'
 
 declare const __remobiConfig: RemobiConfig
 declare const __remobiVersion: string | undefined
+declare const __remobiBasePath: string | undefined
 
 function createSocketUrl(): string {
 	const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
-	return `${protocol}//${window.location.host}/ws`
+	const socketPath = joinBasePath(__remobiBasePath ?? '/', '/ws')
+	return `${protocol}//${window.location.host}${socketPath}`
 }
 
 function attachOptionalAddons(term: Terminal): FitAddon {

src/pwa/manifest.ts

@@ -1,3 +1,4 @@
+import { documentRoute, joinBasePath } from '../base-path'
 import type { PwaConfig } from '../types'
 
 interface WebAppManifest {
@@ -16,22 +17,27 @@ interface WebAppManifest {
 }
 
 /** Generate a web app manifest object from pwa config */
-export function generateManifest(name: string, pwa: PwaConfig): WebAppManifest {
+export function generateManifest(name: string, pwa: PwaConfig, basePath = '/'): WebAppManifest {
 	return {
 		name,
 		short_name: pwa.shortName ?? name,
-		start_url: '/',
+		start_url: documentRoute(basePath),
 		display: 'standalone',
 		background_color: pwa.themeColor,
 		theme_color: pwa.themeColor,
 		icons: [
-			{ src: '/icon-192.png', sizes: '192x192', type: 'image/png', purpose: 'any maskable' },
-			{ src: '/icon-512.png', sizes: '512x512', type: 'image/png' },
+			{
+				src: joinBasePath(basePath, '/icon-192.png'),
+				sizes: '192x192',
+				type: 'image/png',
+				purpose: 'any maskable',
+			},
+			{ src: joinBasePath(basePath, '/icon-512.png'), sizes: '512x512', type: 'image/png' },
 		],
 	}
 }
 
 /** Serialise manifest to JSON string */
-export function manifestToJson(name: string, pwa: PwaConfig): string {
-	return JSON.stringify(generateManifest(name, pwa), null, 2)
+export function manifestToJson(name: string, pwa: PwaConfig, basePath = '/'): string {
+	return JSON.stringify(generateManifest(name, pwa, basePath), null, 2)
 }

src/pwa/meta-tags.ts

@@ -1,3 +1,4 @@
+import { joinBasePath } from '../base-path'
 import type { PwaConfig } from '../types'
 import { ICON_SVG, svgToDataUri } from './icon'
 
@@ -11,14 +12,14 @@ export function escapeAttr(value: string): string {
 }
 
 /** Generate PWA HTML to inject into </head> */
-export function generatePwaHtml(name: string, pwa: PwaConfig): string {
+export function generatePwaHtml(name: string, pwa: PwaConfig, basePath = '/'): string {
 	const svgDataUri = svgToDataUri(ICON_SVG)
 	return [
-		`<link rel="manifest" href="/manifest.json">`,
+		`<link rel="manifest" href="${escapeAttr(joinBasePath(basePath, '/manifest.json'))}">`,
 		`<meta name="theme-color" content="${escapeAttr(pwa.themeColor)}">`,
-		`<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">`,
+		'<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">',
 		`<meta name="apple-mobile-web-app-title" content="${escapeAttr(name)}">`,
-		`<link rel="apple-touch-icon" href="/apple-touch-icon.png">`,
+		`<link rel="apple-touch-icon" href="${escapeAttr(joinBasePath(basePath, '/apple-touch-icon.png'))}">`,
 		`<link rel="icon" type="image/svg+xml" href="${svgDataUri}">`,
 	].join('\n')
 }