diff --git a/.gitignore b/.gitignore
index 0c05a21..83fb59d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ package.json.bak
 
 # Logs
 *.log
+lcov.info
 
 # AI tooling (local-only agent state)
 .agents/
diff --git a/README.md b/README.md
index f7203c2..c087570 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,14 @@
+<img src="assets/social-preview.png" width="600">
+
 # webtty
 
-A web TTY for running CLI/TUI applications in a browser tab, across platforms.
+Terminal UI in the browser. Run CLI/TUI applications in a browser tab, across platforms.
+
+```sh
+npx webtty run        # start server + open a terminal in the browser
+npx webtty ls         # list sessions
+npx webtty help       # show all commands
+```
 
 ## Debugging
 
diff --git a/assets/icon.svg b/assets/icon.svg
new file mode 100644
index 0000000..0bc6d12
--- /dev/null
+++ b/assets/icon.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <rect x="5" y="5" width="90" height="90" rx="18" fill="white"/>
+  <text x="8" y="73" font-size="58" font-family="monospace" font-weight="bold" fill="#161b22">&gt;_</text>
+</svg>
diff --git a/assets/social-preview.png b/assets/social-preview.png
new file mode 100644
index 0000000..a091c81
Binary files /dev/null and b/assets/social-preview.png differ
diff --git a/docs/adrs/002.cli.start-stop.md b/docs/adrs/002.cli.start-stop.md
index 03a0100..bd9cac9 100644
--- a/docs/adrs/002.cli.start-stop.md
+++ b/docs/adrs/002.cli.start-stop.md
@@ -1,4 +1,4 @@
-# ADR 002: CLI — `webtty start` / `webtty stop`
+# ADR 002: CLI — `webtty start` / `webtty stop` / `webtty restart`
 
 **SPEC:** [cli](../specs/cli.md)
 **Status:** Accepted
@@ -26,9 +26,15 @@ Add a CLI entry point (`src/cli.ts`) and a `POST /api/server/stop` endpoint to `
 - Polls `GET /api/sessions` until it responds (or times out), then prints `webtty started`. This ensures the server is actually ready before the CLI exits.
 
 **`webtty stop`**:
-- Sends `POST http://localhost:PORT/api/server/stop`.
-- If the request succeeds: prints `webtty stopped`.
-- If the request fails (connection refused): prints `webtty is not running`.
+- Checks `GET /api/sessions` first — if connection refused, prints `webtty is not running` and exits 0.
+- Otherwise sends `POST http://localhost:PORT/api/server/stop` and polls until the server is down.
+- Prints `webtty stopped` on success, `webtty stop failed` and exits 1 if the server doesn't come down.
+
+**`webtty restart`**:
+- If the server is running, calls the same stop logic (wait for down).
+- Then calls the same start logic (spawn detached, poll until ready).
+- Prints `webtty restarted`.
+- If the server is not running, skips the stop step — restart from cold always works.
 
 **`server.ts` change**: Add `POST /api/server/stop` — kills all PTY sessions, closes the WebSocket server, and calls `process.exit(0)`. The server owns its own shutdown on all platforms.
 
@@ -64,9 +70,9 @@ A `webtty.sh` that does `node dist/server.js &`.
 
 ## Consequences
 
-**Good**: `npx webtty start` works from any directory. Server runs in background, terminal is free. `npx webtty stop` works identically on Mac, Linux, and Windows — no signals, no PID files, no platform-specific code. Server owns its cleanup. No new runtime dependencies.
+**Good**: `npx webtty start` works from any directory. Server runs in background, terminal is free. `npx webtty stop` and `npx webtty restart` work identically on Mac, Linux, and Windows — no signals, no PID files, no platform-specific code. Server owns its cleanup. `stopServer()` is extracted into `http.ts` so `stop` and `restart` share the same wait-for-down logic. No new runtime dependencies.
 
-**Bad**: If the server is hung, `webtty stop` fails silently — acceptable for this slice; hard-kill fallback deferred. Port is hardcoded at 2346 — will become configurable when the config file slice lands.
+**Bad**: If the server is hung, `webtty stop` fails — acceptable for this slice; hard-kill fallback deferred. Port is hardcoded at 2346 — will become configurable when the config file slice lands.
 
 ## Implementation Notes
 
diff --git a/docs/adrs/007.webtty.session-client.md b/docs/adrs/007.webtty.session-client.md
index 74ef5f9..5e76e65 100644
--- a/docs/adrs/007.webtty.session-client.md
+++ b/docs/adrs/007.webtty.session-client.md
@@ -39,7 +39,15 @@ When the PTY exits (e.g. user types `exit`), the server:
 1. Deletes the session from the registry immediately
 2. Closes all connected WebSockets with code `4001`
 
-The client's existing `4001` handler (introduced in ADR 005 for deleted sessions) writes "Session removed." and calls `window.close()` after 2s. No delay is added before closing — the user explicitly typed `exit`, so immediate closure is the right behaviour. All open tabs for that session close together.
+The client's existing `4001` handler (introduced in ADR 005 for deleted sessions) writes "Session removed." and calls `window.close()` after 500ms. No delay is added before closing — the user explicitly typed `exit`, so immediate closure is the right behaviour. All open tabs for that session close together.
+
+Server stop (`webtty stop` or SIGINT) sends close code `1001` instead. The client writes "Server stopped." and also calls `window.close()` after 500ms.
+
+**`window.close()` browser restriction**: browsers only permit `window.close()` on tabs that were opened via `window.open()` or duplicated from such a tab. Tabs opened by the OS `open`/`xdg-open` command or by the user typing a URL directly are treated as unowned — `window.close()` is silently ignored with a console warning. In practice this means:
+- Tabs opened by `webtty run` and tabs duplicated from them → close automatically ✅
+- Tabs opened by manually navigating to `localhost:2346` → show "Server stopped." / "Session removed." but remain open ⚠️
+
+There is no JS workaround for this restriction. It is browser-enforced by design.
 
 **Multi-tab: fanout to all connected clients**
 
@@ -102,4 +110,5 @@ Only the first/oldest connected tab can send input; additional tabs are viewers.
 ## Related Decisions
 
 - [ADR 005 — UI Session Support](005.client.session-support.md): Established session persistence across WS disconnects and the `4001` close code
+- [ADR 010 — Client UX polish](010.client.ux-polish.md): Redesigned the welcome banner and unified status message styling
 
diff --git a/docs/adrs/008.webtty.config.md b/docs/adrs/008.webtty.config.md
new file mode 100644
index 0000000..da87b7d
--- /dev/null
+++ b/docs/adrs/008.webtty.config.md
@@ -0,0 +1,71 @@
+# ADR 008: webtty — Config File
+
+**SPEC:** [config](../specs/config.md)
+**Status:** Accepted
+**Date:** 2026-03-23
+
+---
+
+## Context
+
+All webtty settings are currently hardcoded or read from environment variables only. Users have no persistent way to change port, shell, terminal appearance, or theme without modifying source or wrapping the binary in a shell script. ADR 002 explicitly deferred this: "Port is hardcoded at 2346 — will become configurable when the config file slice lands."
+
+Three concerns drive the design:
+
+1. **Where is the file?** It must follow platform conventions and be easy to find.
+2. **What format?** Must be human-editable; comments are essential for a config file users edit directly.
+3. **What is the load/merge strategy?** Adding new keys in future versions must not break existing configs.
+
+## Decision
+
+**File location**: `~/.config/webtty/config.json` — follows the XDG Base Directory convention used by most modern CLI tools (opencode, lazygit, starship, etc.). Created automatically on first run with only `port` and `host` set.
+
+**Format**: Plain JSON. The file is written by `saveConfig` using `JSON.stringify` and read with `JSON.parse`. Comments are not supported — the schema table in the [config spec](../specs/config.md) serves as documentation. This removes the `strip-json-comments` dependency and keeps the parser a zero-config standard library call.
+
+**Load strategy**: Merge partial config over defaults — unknown keys are ignored, missing keys fall back to built-in defaults. This means adding new config keys in future versions is non-breaking: an old `config.jsonc` with only `port` still works correctly with a binary that added `theme`.
+
+**Env overrides**: `PORT` overrides `config.port` at runtime. Applied after file load, never written back to the file.
+
+**Terminal config delivery**: Server-side config values that affect the browser terminal (cols, rows, fontSize, fontFamily, cursorBlink, scrollback lines, theme) are injected into the HTML template returned by `GET /s/:id`. The client reads them from the rendered page — no separate API endpoint needed.
+
+**`scrollback`**: A single value in bytes (`256 * 1024` default). Controls both the server-side PTY replay ring buffer (`session.ts`) and the client-side terminal line buffer (derived as `Math.ceil(scrollback / 80)` — assumes ~80 bytes/line average). One knob, one mental model.
+
+## Considered Options
+
+**Option A: `.webtty/config.json` in home directory**
+
+- **Pros**: Simple, familiar to Node.js users.
+- **Cons**: Clutters `~` with a dot-directory. XDG convention (`~/.config/`) is now the standard for CLI tools.
+
+**Option B: TOML format**
+
+- **Pros**: More readable for nested structures (theme colors).
+- **Cons**: Requires a TOML parser dependency (~50 KB). JSON is sufficient and consistent with the existing JSON surface (REST API, `package.json`).
+
+**Option C: Separate env var for every setting**
+
+- **Pros**: No new file format.
+- **Cons**: Env vars are session-scoped, not persistent. Unwieldy for nested settings like theme colors. Users expect a config file for terminal emulators.
+
+**Option D: Bun-native JSONC only**
+
+- **Pros**: Zero bytes added to bundle.
+- **Cons**: Breaks Node.js compatibility. webtty explicitly supports both runtimes.
+
+**Option E: JSONC via `strip-json-comments`**
+
+- **Pros**: Users can annotate their config with comments.
+- **Cons**: Adds a dependency for a cosmetic feature. The schema table in the spec is a better reference than inline comments in a generated file. Dropped in favour of plain JSON.
+
+## Consequences
+
+- First run creates `~/.config/webtty/config.json` with `port` and `host` set — users have a ready-to-edit file immediately
+- `port`, `host`, `shell`, `term`, `scrollback`, `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, and `theme` are all user-configurable
+- Adding new config keys in future versions is non-breaking
+- No additional production dependencies — `JSON.parse` is sufficient
+- Terminal appearance config is injected server-side into the HTML — no client-side config fetch needed
+
+## Related Decisions
+
+- [ADR 002 — CLI start/stop](002.cli.start-stop.md): explicitly deferred config file; port hardcoded at 2346
+- [ADR 007 — Session client](007.webtty.session-client.md): terminal defaults (cols, rows, theme) previously hardcoded in `client.ts`
diff --git a/docs/adrs/009.webtty.config-hot-reload.md b/docs/adrs/009.webtty.config-hot-reload.md
new file mode 100644
index 0000000..992c4be
--- /dev/null
+++ b/docs/adrs/009.webtty.config-hot-reload.md
@@ -0,0 +1,51 @@
+# ADR 009: webtty — Config Hot Reload
+
+**SPEC:** [config](../specs/config.md)
+**Status:** Accepted
+**Date:** 2026-03-23
+
+---
+
+## Context
+
+Config is currently loaded once at server startup and held in memory for the lifetime of the process. Users who edit `~/.config/webtty/config.json` must restart the server to see their changes — even for purely cosmetic settings like font size or theme colors.
+
+A full hot-reload (e.g. `fs.watch` triggering a live update mid-session) is impractical: the terminal is already initialized in the browser with the old values, and pushing new font/theme settings to a live xterm instance requires non-trivial client-side logic. However, a tab reload already reconstructs the terminal from scratch — the browser fetches `GET /s/:id`, the server renders fresh HTML with config injected, and the client re-initializes xterm. This is a natural reload boundary.
+
+## Decision
+
+**Re-read `config.json` on every `GET /s/:id` request** instead of using the startup-cached value. No file watcher, no WebSocket push, no client changes.
+
+- `loadConfig()` is called inside the `GET /s/:id` handler, not at module load time.
+- `port` and `host` remain read once at startup — they are bound to the OS socket and cannot change without a restart.
+- `shell` and `term` are re-read when a new PTY is spawned (first WebSocket connection to a session that has no running shell). An already-running session is unaffected.
+- All appearance settings (`cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, `scrollback`, `theme`) take effect immediately on the next tab reload.
+
+## Considered Options
+
+**Option A: `fs.watch` + WebSocket push to live terminal**
+
+- **Pros**: Truly live — no reload needed.
+- **Cons**: Requires client-side logic to apply new theme/font to a running xterm instance. xterm's `Terminal.options` setter works for some properties but not all (e.g. `fontFamily` requires a full re-render). Significant complexity for marginal benefit — users editing config will naturally reload anyway.
+
+**Option B: Re-read on every request (chosen)**
+
+- **Pros**: Zero client changes. Zero file watcher infrastructure. Works with the existing reload boundary. The extra `fs.readFileSync` per page load is negligible (config file is ~3 KB, loaded once per tab open).
+- **Cons**: Config changes don't apply to a live tab without a reload — acceptable given the use case.
+
+**Option C: Keep startup-only load, add `POST /api/config/reload` endpoint**
+
+- **Pros**: Explicit reload, avoids per-request I/O.
+- **Cons**: Requires the user to manually hit an endpoint or use a CLI command. Tab reload is already the natural trigger; adding an extra step is worse UX.
+
+## Consequences
+
+- Editing `~/.config/webtty/config.json` and reloading the browser tab picks up all appearance changes immediately — no server restart needed.
+- `shell`, `term`, `colorTerm`, and `scrollback` are re-read when a new PTY is spawned — no server restart needed for shell changes either.
+- `port` / `host` changes still require a server restart (expected; the socket is already bound).
+- `loadConfig()` adds one `fs.readFileSync` + JSON parse per tab load and per new PTY spawn — negligible cost.
+- `createWebSocketServer` no longer accepts a `config` parameter — it calls `loadConfig()` itself at PTY spawn time. `index.ts` retains a startup-cached config only for `port`/`host` (server bind).
+
+## Related Decisions
+
+- [ADR 008 — Config file](008.webtty.config.md): established config file location, format, and load strategy
diff --git a/docs/adrs/010.client.ux-polish.md b/docs/adrs/010.client.ux-polish.md
new file mode 100644
index 0000000..8089a94
--- /dev/null
+++ b/docs/adrs/010.client.ux-polish.md
@@ -0,0 +1,103 @@
+# ADR 010: webtty — Client UX polish (banner, status messages)
+
+**SPEC:** [client](../specs/client.md)
+**Status:** Accepted
+**Date:** 2026-03-24
+
+---
+
+## Context
+
+The original welcome banner was ported verbatim from the `ghostty-web` demo — a colorful multi-line box with tutorial-style copy ("You have a real shell session with full PTY support. Try: ls, cd, top, vim..."). The disconnect messages used ad-hoc inline ANSI codes with inconsistent colors (red for session removal, yellow for server stop).
+
+Three problems:
+
+1. **Banner feels like a demo artifact** — the content is aimed at first-time ghostty-web users, not webtty users. It does not identify the product or give actionable guidance.
+2. **No visual identity** — nothing in the UI surfaces the `webtty` name or how to get help.
+3. **Inconsistent status messages** — each WS event had its own inline color and wording with no shared style.
+
+## Decision
+
+### Welcome banner
+
+A structured box with two content lines separated by a blank line:
+
+```
+╔══════════════════════════════════════════════════════╗
+║                                                      ║
+║ [ webtty ]   Terminal UI in the browser              ║
+║                                                      ║
+║ Run `bunx webtty help` for more information.         ║
+║                                                      ║
+╚══════════════════════════════════════════════════════╝
+```
+
+**Line 1 — identity + slogan:**
+- `[` `]` — dim (ANSI `\x1b[2m`) so they frame without competing
+- `webtty` — bold yellow (`\x1b[1;33m`), the only high-contrast element in the banner
+- slogan `Terminal UI in the browser` — dim, recedes behind the name
+
+**Line 2 — help:**
+- `Run` and `for more information.` — dim plain
+- `` `bunx webtty help` `` — foreground italic (`\x1b[3m`), the actionable part
+
+**Border:** bright cyan (`\x1b[1;36m`) double-line box.
+
+**Package runner detection:** `process.execPath.includes('bun')` at server startup — shows `bunx` under Bun, `npx` under Node.
+
+The banner is shown only on first connect (when `session.pty` is `null`) and written into `session.scrollback` so it appears on replay. Unchanged from ADR 007.
+
+### Status messages
+
+All WS lifecycle events that write to the terminal share a single helper:
+
+```
+[ webtty ] <message>
+```
+
+- `[ webtty ]` — dim brackets, bold yellow name (same identity as the banner)
+- Message text — dim italic (`\x1b[2m\x1b[3m`)
+
+| Close code | Message | Action |
+|------------|---------|--------|
+| `4001` | `Session removed.` | `window.close()` after 500ms |
+| `1001` | `Server stopped.` | `window.close()` after 500ms |
+| other | `Connection lost. Reconnecting in 2s...` | reconnect after 2s |
+| `onerror` | `WebSocket error.` | — |
+
+### `onopen` / `onerror` / `console` policy
+
+- `ws.onopen` — no terminal message, no `console.log`. The shell prompt appearing is self-evident.
+- `ws.onerror` — `term.write(msg(...))` only. No `console.error`.
+- `ws.onclose` — `term.write(msg(...))` only. No `console.log`.
+
+No user-facing event writes to both `term.write` and `console` — terminal output is the single source of truth for the user.
+
+## Considered Options
+
+**Option A: No banner (like SSH / macOS Terminal)**
+
+Rejected — webtty is a web app with a CLI. First-time users need to know where to get help. A minimal banner with the app name and a single help hint is enough.
+
+**Option B: Keep the ghostty-web demo banner**
+
+Rejected — tutorial copy ("Try: ls, cd, top, vim") is condescending for users who know what a terminal is. The product name and help command are more useful.
+
+**Option C: Session ID in the banner**
+
+Rejected — the session ID is already in the browser tab title (`webtty — <id>`). Repeating it in the terminal adds noise.
+
+**Option D: Per-event colors for status messages (red for errors, yellow for warnings)**
+
+Rejected — color-coded severity for these three events adds visual noise with little signal gain. The `[ webtty ]` prefix already distinguishes these messages from shell output. Consistent dim italic is quieter and more readable.
+
+## Consequences
+
+- The banner surfaces the product name and a single actionable help command — no tutorial noise.
+- All status messages share the same `[ webtty ]` identity pattern — consistent with the banner.
+- The package runner (`bunx` vs `npx`) is detected at server startup — correct for the user's environment without configuration.
+- `onerror` events now surface in the terminal, previously they were silent to the user (console only).
+
+## Related Decisions
+
+- [ADR 007 — Session client](007.webtty.session-client.md): established banner placement (first connect only), scrollback inclusion, and WS close code semantics
diff --git a/docs/adrs/011.cli.default-and-help.md b/docs/adrs/011.cli.default-and-help.md
new file mode 100644
index 0000000..d29e6b4
--- /dev/null
+++ b/docs/adrs/011.cli.default-and-help.md
@@ -0,0 +1,78 @@
+# ADR 011: CLI — `webtty` (no-arg entry point) and `webtty help`
+
+**SPEC:** [cli](../specs/cli.md)
+**Status:** Proposed
+**Date:** 2026-03-24
+
+---
+
+## Context
+
+Two CLI entry points are missing that users will naturally reach for:
+
+1. **`webtty`** (no arguments) — the most obvious invocation. Currently falls through to Commander's default "display help" behaviour, which is surprising: a user running `npx webtty` for the first time expects something to happen, not a help page.
+
+2. **`webtty help`** — the banner in every terminal session tells users to run `` `bunx webtty help` `` for more information. That command currently fails with "unknown command". The banner promises something that doesn't exist.
+
+## Decision
+
+### `webtty` (no args)
+
+Equivalent to `webtty run main`:
+
+1. Start the server if not already running (same logic as `webtty run`)
+2. Create or reuse the `main` session
+3. Open the session URL in the default browser
+
+This is the "just works" entry point — the one you'd put in a README quickstart:
+
+```sh
+npx webtty
+```
+
+**Why `main` and not a generated ID?** `main` is already the default session created by `GET /`. It is a stable, predictable name. Users who open a second terminal can run `webtty run` with an explicit ID without interfering with `main`.
+
+**`NODE_ENV=test` guard:** same as `openBrowser` — suppressed in test environments to avoid spawning real browser tabs during `bun test`.
+
+### `webtty help`
+
+An explicit alias for `--help` — prints the same Commander-generated help output:
+
+```
+Usage: webtty [options] [command]
+
+Web TTY — run terminal sessions in a browser tab
+...
+```
+
+This makes the banner's call-to-action (`Run \`bunx webtty help\` for more information.`) functional. It does not replace `--help`; both work.
+
+## Considered Options
+
+**Option A: `webtty` opens a new session with a generated ID (not `main`)**
+
+- **Pros**: Each invocation is a fresh session, no risk of reusing a stale session.
+- **Cons**: Multiple invocations accumulate zombie sessions. `main` is predictable and idiomatic — consistent with the server's own default redirect behaviour (`GET /` → `main`).
+
+**Option B: `webtty` only starts the server, no browser open**
+
+- **Pros**: Safer, no side effects beyond the server process.
+- **Cons**: Requires a second command to actually open a terminal. Defeats the purpose of a frictionless entry point.
+
+**Option C: `webtty help` renders a rich custom help page**
+
+- **Pros**: More control over formatting.
+- **Cons**: Maintenance burden — Commander already generates good help output and keeps it in sync with registered commands automatically.
+
+## Consequences
+
+- `npx webtty` / `bunx webtty` becomes the canonical quickstart — one command to go from zero to a browser terminal.
+- The banner's `Run \`bunx webtty help\`` call-to-action becomes functional.
+- `webtty run main` remains the explicit equivalent — no behaviour change for existing users.
+- The no-arg path reuses all existing `run` logic — minimal new code.
+
+## Related Decisions
+
+- [ADR 002 — CLI start/stop](002.cli.start-stop.md): established `startServer` and `isServerRunning` used by the no-arg path
+- [ADR 006 — CLI session management](006.cli.session-management.md): established `webtty run` which the no-arg path delegates to
+- [ADR 010 — Client UX polish](010.client.ux-polish.md): the banner that references `webtty help`
diff --git a/docs/specs/cli.md b/docs/specs/cli.md
index 38497b1..6fd8854 100644
--- a/docs/specs/cli.md
+++ b/docs/specs/cli.md
@@ -27,7 +27,9 @@ The CLI communicates with the server exclusively over HTTP to localhost — no U
 | `webtty run [id]` | Start server if not running; create session (auto-generates ID if omitted) or reuse if ID exists; open session URL in the default browser |
 | `webtty rm <id>` | `DELETE /api/sessions/:id` — kill session and its PTY |
 | `webtty rename <id> <new-id>` | `PATCH /api/sessions/:id` — rename a session; session URL updates to reflect new id |
-| `webtty restart` | Stop + start | ⬜ not yet implemented |
+| `webtty restart` | Stop + start |
+| `webtty` | No-arg entry point — start server if not running, open `main` session in browser | ⬜ |
+| `webtty help` | Alias for `--help` — print all commands | ⬜ |
 
 ## Features
 
@@ -35,4 +37,6 @@ The CLI communicates with the server exclusively over HTTP to localhost — no U
 |---------|-------------|-----|-------|
 | Server lifecycle | `webtty start` / `stop` — fork, detect, and terminate the server over HTTP | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
 | Session management | `webtty run` / `ls` / `rm` / `rename` — create, list, remove, and rename sessions via the REST API | [ADR 006](../adrs/006.cli.session-management.md) | ✅ |
-| Server restart | `webtty restart` — stop then start; `POST /api/server/restart` on server side | — | ⬜ |
+| Server restart | `webtty restart` — stop then start | [ADR 002](../adrs/002.cli.start-stop.md) | ✅ |
+| No-arg entry point | `webtty` — start server + open `main` session in browser | [ADR 011](../adrs/011.cli.default-and-help.md) | ⬜ |
+| Help command | `webtty help` — alias for `--help` | [ADR 011](../adrs/011.cli.default-and-help.md) | ⬜ |
diff --git a/docs/specs/client.md b/docs/specs/client.md
index f3a2ae0..4ae5aaf 100644
--- a/docs/specs/client.md
+++ b/docs/specs/client.md
@@ -1,7 +1,7 @@
 # SPEC: Client
 
 **Author:** jesse23
-**Last Updated:** 2026-03-22
+**Last Updated:** 2026-03-24
 
 ---
 
@@ -15,11 +15,71 @@ The client has no build step in the initial slices — plain HTML + `<script typ
 
 **Why no framework (React/Vue) yet?** The session manager is simple enough (a table + buttons) that a framework adds more complexity than it removes. Revisit when the client grows.
 
+## Page
+
+`GET /s/:id` returns a full-viewport HTML page. It:
+
+- Initialises a `ghostty-web` `Terminal` with config values (cols, rows, fontSize, fontFamily, cursorBlink, scrollback, theme) injected server-side at render time
+- Connects to `ws://<host>/ws/:id?cols=<cols>&rows=<rows>` over WebSocket
+- Fits the terminal to the viewport and observes resize events via `FitAddon`
+- Sends a `{ type: 'resize', cols, rows }` JSON message on open and on every terminal resize
+- Forwards all keystrokes to the PTY via `term.onData`
+
+## Welcome Banner
+
+On the first WebSocket connection to a session (no existing PTY), the server writes a banner to the terminal:
+
+```
+╔══════════════════════════════════════════════════════╗
+║                                                      ║
+║ [ webtty ]   Terminal UI in the browser              ║
+║                                                      ║
+║ Run `bunx webtty help` for more information.         ║
+║                                                      ║
+╚══════════════════════════════════════════════════════╝
+```
+
+- `[ webtty ]` — dim brackets, bold yellow name
+- Slogan — dim
+- Help command — dim italic surroundings, foreground italic for the command itself
+- Package runner (`bunx` or `npx`) is detected from the server's runtime at startup
+
+## Status Messages
+
+All status messages written to the terminal share a consistent style:
+
+```
+[ webtty ] <message>
+```
+
+- `[ webtty ]` — dim brackets, bold yellow name (matches banner)
+- Message — dim italic
+
+| Event | Message | Behavior |
+|-------|---------|----------|
+| WS close `4001` (session deleted / shell exited) | `Session removed.` | `window.close()` after 500ms |
+| WS close `1001` (server stopped) | `Server stopped.` | `window.close()` after 500ms |
+| WS close (unexpected) | `Connection lost. Reconnecting in 2s...` | Reconnect after 2s |
+| WS error | `WebSocket error.` | — |
+
+## Behavior Notes
+
+### Tab close on session end
+
+When a session ends (shell exits → WS close code `4001`) or the server stops (`webtty stop` / SIGINT → WS close code `1001`), the client calls `window.close()` after 500 ms to close the tab automatically.
+
+**Browser restriction**: `window.close()` is only permitted on tabs that were opened programmatically via `window.open()`, or duplicated from such a tab. Tabs opened by the OS (`open`/`xdg-open`) or by the user typing a URL directly are treated as unowned — `window.close()` is silently ignored. In practice:
+
+- Tabs opened by `webtty run` and tabs duplicated from them → close automatically ✅
+- Tabs opened by manually navigating to the server URL → display the status message but remain open ⚠️
+
+This is a browser-enforced security restriction with no JS workaround.
+
 ## Features
 
 | Feature | Description | ADR | Done? |
 |---------|-------------|-----|-------|
 | Terminal view | Full-viewport terminal using `ghostty-web`, auto-fit, reconnect on disconnect | [001](../adrs/001.webtty.bootstrap.md) | ✅ |
-| Session support | `<url>/s/:id` opens a named session; `<url>` redirects to the last-used session or creates a new one with a generated readable name (e.g. `main`) if none exists | [ADR 005](../adrs/005.client.session-support.md) | ✅ |
-| Session manager | List sessions, open in new tab, create new session, kill session | — | ⬜ |
-| Server control | Restart and stop server from the client (calls server control API) | — | ⬜ |
+| Session support | `<url>/s/:id` opens a named session; `<url>` redirects to the last-used session or creates `main` if none exists | [ADR 005](../adrs/005.client.session-support.md) | ✅ |
+| Welcome banner | Shown on first connection to a session; identifies app, slogan, and help command | [ADR 010](../adrs/010.client.ux-polish.md) | ✅ |
+| Status messages | Consistent `[ webtty ]`-prefixed dim italic messages for disconnect, error, and server stop events | [ADR 010](../adrs/010.client.ux-polish.md) | ✅ |
diff --git a/docs/specs/config.md b/docs/specs/config.md
new file mode 100644
index 0000000..50f0574
--- /dev/null
+++ b/docs/specs/config.md
@@ -0,0 +1,197 @@
+# SPEC: Config
+
+**Author:** jesse23
+**Last Updated:** 2026-03-23
+
+---
+
+## Description
+
+webtty reads configuration from `~/.config/webtty/config.json`. It is the single source of truth for persistent user preferences. Environment variables override config file values at runtime but never modify the file.
+
+## File location
+
+| Platform | Path |
+|----------|------|
+| macOS / Linux | `~/.config/webtty/config.json` |
+| Windows | `%USERPROFILE%\.config\webtty\config.json` |
+
+## Lifecycle
+
+### Server startup
+
+```
+webtty server starts
+   │
+   ▼
+config file exists? ────────────────────┐
+   │                                    │
+  yes                                   no
+   │                                    │
+   ▼                                    ▼
+read + parse JSON               write defaults to file
+   │                                    │
+   │                              write fails?
+   │                                    │
+   │                            warn to stderr +
+   │                            use defaults in memory ──► port/host locked
+   ▼
+valid JSON?
+   │
+  no ──► hard error: print path, exit
+   │
+  yes
+   ▼
+merge with defaults
+(unknown keys ignored)
+   │
+   ▼
+apply env overrides
+(PORT > config.port, etc.)
+   │
+   ▼
+port/host locked for server lifetime
+```
+
+### Browser tab load / reload  (`GET /s/:id`)
+
+```
+browser requests /s/:id
+   │
+   ▼
+loadConfig() — re-read file from disk
+   │
+   ▼
+render HTML with fresh appearance settings injected:
+cols, rows, fontSize, fontFamily, cursorBlink, scrollback, theme
+```
+
+### New PTY spawn  (first WebSocket connection to a session)
+
+```
+WebSocket connects to /ws/:id
+   │
+   ▼
+session has no running PTY?
+   │
+  yes
+   ▼
+loadConfig() — re-read file from disk
+   │
+   ▼
+spawn PTY with fresh: shell, term, colorTerm, scrollback
+```
+
+### Rules
+
+- **First run**: defaults are written to disk so the user has a file to edit.
+- **Subsequent runs**: file is read and merged with defaults — missing keys fall back to defaults, so adding new config keys in future versions is non-breaking.
+- **Write failure on first run**: warns to stderr, continues with in-memory defaults (no crash).
+- **Invalid JSON**: hard error with a clear message pointing to the file path. webtty does not attempt to repair or overwrite a corrupt file.
+- **Unknown keys**: silently ignored (forward-compatibility — a config written by a newer version works with an older binary).
+- **Env overrides**: `PORT` overrides `config.port` at runtime. Applied after file load, never written back.
+- **Hot config reload**:
+  - `port` / `host` — locked at startup (server socket already bound; restart required).
+  - `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink`, `scrollback`, `theme` — re-read on every tab reload.
+  - `shell`, `term`, `colorTerm`, `scrollback` — re-read when a new PTY is spawned (i.e. first connection to a session that has no running shell).
+  - An already-running session is never affected mid-flight.
+
+## Schema
+
+All keys are optional — omit any key to use the default value.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `port` | number | `2346` | HTTP listen port; env `PORT` takes precedence |
+| `host` | string | `"127.0.0.1"` | Bind address; use `"0.0.0.0"` for remote access |
+| `shell` | string | `$SHELL` / `%COMSPEC%` | Shell for new sessions |
+| `term` | string | `$TERM` | `$TERM` env var passed to the shell |
+| `colorTerm` | string | `"truecolor"` | `$COLORTERM` env var passed to the shell |
+| `scrollback` | number | `262144` | PTY history buffer in bytes; used for server-side replay on reload/reconnect |
+| `cols` | number | `80` | Initial terminal width in columns |
+| `rows` | number | `24` | Initial terminal height in rows |
+| `cursorBlink` | boolean | `true` | Whether the cursor blinks |
+| `fontSize` | number | `13` | Font size in px |
+| `fontFamily` | string | `"Menlo, Consolas, 'DejaVu Sans Mono', monospace"` | CSS font-family stack |
+| `theme` | object | Campbell | Terminal color palette — see theme keys below |
+
+### Theme keys
+
+All theme keys are optional; omitted keys fall back to the Campbell (Windows Terminal default) palette.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `background` | `#000000` | Terminal background |
+| `foreground` | `#CCCCCC` | Default text color |
+| `cursor` | `#FFFFFF` | Cursor color |
+| `selection` | `#FFFFFF` | Selection highlight |
+| `black` | `#0C0C0C` | ANSI 0 |
+| `red` | `#C50F1F` | ANSI 1 |
+| `green` | `#13A10E` | ANSI 2 |
+| `yellow` | `#C19C00` | ANSI 3 |
+| `blue` | `#0037DA` | ANSI 4 |
+| `purple` | `#881798` | ANSI 5 |
+| `cyan` | `#3A96DD` | ANSI 6 |
+| `white` | `#CCCCCC` | ANSI 7 |
+| `brightBlack` | `#767676` | ANSI 8 |
+| `brightRed` | `#E74856` | ANSI 9 |
+| `brightGreen` | `#16C60C` | ANSI 10 |
+| `brightYellow` | `#F9F1A5` | ANSI 11 |
+| `brightBlue` | `#3B78FF` | ANSI 12 |
+| `brightPurple` | `#B4009E` | ANSI 13 |
+| `brightCyan` | `#61D6D6` | ANSI 14 |
+| `brightWhite` | `#F2F2F2` | ANSI 15 |
+
+### Example
+
+```json
+{
+  "port": 2346,
+  "host": "127.0.0.1",
+
+  "shell": "/bin/zsh",
+  "term": "xterm-256color",
+
+  "scrollback": 262144,
+  "cols": 80,
+  "rows": 24,
+  "cursorBlink": true,
+  "fontSize": 13,
+  "fontFamily": "Menlo, Consolas, 'DejaVu Sans Mono', monospace",
+
+  "theme": {
+    "background":   "#000000",
+    "foreground":   "#CCCCCC",
+    "cursor":       "#FFFFFF",
+    "selection":    "#FFFFFF",
+    "black":        "#0C0C0C",
+    "red":          "#C50F1F",
+    "green":        "#13A10E",
+    "yellow":       "#C19C00",
+    "blue":         "#0037DA",
+    "purple":       "#881798",
+    "cyan":         "#3A96DD",
+    "white":        "#CCCCCC",
+    "brightBlack":  "#767676",
+    "brightRed":    "#E74856",
+    "brightGreen":  "#16C60C",
+    "brightYellow": "#F9F1A5",
+    "brightBlue":   "#3B78FF",
+    "brightPurple": "#B4009E",
+    "brightCyan":   "#61D6D6",
+    "brightWhite":  "#F2F2F2"
+  }
+}
+```
+
+## Features
+
+| Feature | Description | ADR | Done? |
+|---------|-------------|-----|-------|
+| Config lifecycle | First-run write + subsequent load, merge with defaults, env overrides | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `port` / `host` | Override HTTP listen port and bind address | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `shell` / `term` / `colorTerm` | Override shell and `$TERM` / `$COLORTERM` env vars for new PTY sessions | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `scrollback` | PTY history buffer size in bytes; shared between server-side replay and client-side line buffer | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| Terminal appearance | `cols`, `rows`, `fontSize`, `fontFamily`, `cursorBlink` injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| `theme` | Terminal color palette injected into client HTML | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
+| Hot config reload | Appearance re-read on tab reload; shell/PTY settings re-read on new PTY spawn; `port`/`host` locked for server lifetime | [ADR 009](../adrs/009.webtty.config-hot-reload.md) | ✅ |
diff --git a/docs/specs/release-process.md b/docs/specs/release-process.md
index 6463b5d..64c72a0 100644
--- a/docs/specs/release-process.md
+++ b/docs/specs/release-process.md
@@ -125,6 +125,6 @@ main branch:
 
 | Feature | Status | Reference |
 |---------|--------|-----------|
-| Automated versioning via conventional commits | ⬜ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
-| npm publish on release | ⬜ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
-| GitHub Release with release notes | ⬜ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
+| Automated versioning via conventional commits | ✅ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
+| npm publish on release | ✅ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
+| GitHub Release with release notes | ✅ | [ADR 003](../adrs/003.release-process.semantic-release.md) |
diff --git a/docs/specs/webtty.md b/docs/specs/webtty.md
index e9ab318..04fc717 100644
--- a/docs/specs/webtty.md
+++ b/docs/specs/webtty.md
@@ -21,7 +21,7 @@ The goal is the same as ttyd and GoTTY: zero client-side installation, full TUI
 
 Sessions are PTY instances keyed by ID. Each session has a unique ID and a running PTY process. Sessions survive WebSocket disconnects but not server restarts (memory-only — webtty defers long-lived persistence to `tmux`/`screen`).
 
-New sessions use the user's default shell from the environment (`$SHELL` on POSIX, `%COMSPEC%` on Windows). No per-session command override.
+New sessions use the shell configured in `~/.config/webtty/config.json` (defaults to `$SHELL` on POSIX, `%COMSPEC%` on Windows). No per-session command override.
 
 ### Session data model
 
@@ -36,10 +36,10 @@ interface Session {
 ### Session lifecycle
 
 ```
-                    WS connect                   WS connect (more clients)
-                   (PTY spawns)                  (scrollback replayed)
-                       │                                │
-  POST /api/sessions   │      all clients disconnect    │
+                    WS connect                WS connect (more clients)
+                   (PTY spawns)               (scrollback replayed)
+                       │                             │
+  POST /api/sessions   │   all clients disconnect    │
   ────────────────► [idle] ◄──────────────────── [active] ──► [active]
                        │                            │         clients: 1..N
                        │                            │
@@ -51,8 +51,6 @@ interface Session {
 
 Sessions survive client disconnects — the PTY keeps running while idle. Multiple clients can attach to the same session simultaneously; PTY output is broadcast to all.
 
-
-
 Session IDs appear directly in the URL path (`/s/:id`), so they must be valid URL path segments:
 
 - Allowed characters: `a-z`, `0-9`, `-`, `_`, `.`
@@ -82,10 +80,10 @@ Session IDs appear directly in the URL path (`/s/:id`), so they must be valid UR
 
 | Feature | Description | ADR | Done? |
 |---------|-------------|-----|-------|
-| Bootstrap | Port `ghostty-web` demo into webtty — full-screen terminal in a browser tab, single server, hardcoded config | [001](../adrs/001.webtty.bootstrap.md) | ⬜ |
-| Config file | Load shell, port, font, theme from a config file (`~/.webtty/config.json`) | — | ⬜ |
+| Bootstrap | Port `ghostty-web` demo into webtty — full-screen terminal in a browser tab, single server, hardcoded config | [001](../adrs/001.webtty.bootstrap.md) | ✅ |
 | In-memory registry | Server-side map of `id → { session, pty }`; sessions survive WS disconnect, not server restart | — | ✅ |
 | Default session | `GET /` redirects to last-used session, or creates `main` and redirects if none exists | — | ✅ |
 | Session URL | `GET /s/:id` — serves browser client for the named session; reconnects if session already has a PTY | — | ✅ |
 | Session management | CRUD + rename over HTTP — see REST API above | [ADR 004](../adrs/004.webtty.session-api.md) | ✅ |
+| Config file | Load shell, port, font, theme from `~/.config/webtty/config.json`; hot-reload on tab reload | [ADR 008](../adrs/008.webtty.config.md) | ✅ |
 | Session client | Multiple browser tabs can attach to the same session simultaneously; reload replays scrollback; typing `exit` closes all tabs | [ADR 007](../adrs/007.webtty.session-client.md) | ✅ |
diff --git a/package.json b/package.json
index 08b7036..397e485 100644
--- a/package.json
+++ b/package.json
@@ -3,8 +3,7 @@
   "version": "0.0.0-development",
   "description": "Web TTY for running CLI/TUI applications in a browser tab, across platforms",
   "bin": {
-    "webtty": "dist/cli/index.js",
-    "wtty": "dist/cli/index.js"
+    "webtty": "dist/cli/index.js"
   },
   "files": [
     "dist"
@@ -19,6 +18,7 @@
     "lint": "tsc --noEmit -p tsconfig.lint.json && biome check .",
     "lint:fix": "tsc --noEmit -p tsconfig.lint.json && bunx biome check --write .",
     "test": "bun test",
+    "test:coverage": "bun test --coverage",
     "build": "bun run scripts/build.ts",
     "server": "bun run dist/server/index.js",
     "server:node": "node dist/server/index.js",
diff --git a/src/cli/commands.test.ts b/src/cli/commands.test.ts
index 72166dc..34f32c0 100644
--- a/src/cli/commands.test.ts
+++ b/src/cli/commands.test.ts
@@ -106,6 +106,23 @@ describe('cli — lifecycle', () => {
     expect(exitCode).toBe(0);
     expect(stdout).toBe('webtty is not running');
   });
+
+  test('restart starts the server when not running', async () => {
+    const { stdout, exitCode } = await runCli(port, 'restart');
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe('webtty restarted');
+    expect(await waitForServer(baseUrl)).toBe(true);
+  });
+
+  test('restart stops and restarts a running server', async () => {
+    const resBefore = await fetch(`${baseUrl}/api/sessions`);
+    expect(resBefore.ok).toBe(true);
+
+    const { stdout, exitCode } = await runCli(port, 'restart');
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe('webtty restarted');
+    expect(await waitForServer(baseUrl)).toBe(true);
+  });
 });
 
 describe('cli — session management', () => {
diff --git a/src/cli/commands.ts b/src/cli/commands.ts
index 7807815..3972ae2 100644
--- a/src/cli/commands.ts
+++ b/src/cli/commands.ts
@@ -1,5 +1,5 @@
 import type { Command } from 'commander';
-import { BASE_URL, isServerRunning, openBrowser, startServer } from './http';
+import { BASE_URL, isServerRunning, openBrowser, startServer, stopServer } from './http';
 
 export function registerCommands(program: Command): void {
   program
@@ -18,16 +18,16 @@ export function registerCommands(program: Command): void {
     .command('stop')
     .description('Stop the webtty server')
     .action(async () => {
-      try {
-        const res = await fetch(`${BASE_URL}/api/server/stop`, { method: 'POST' });
-        if (res.ok) {
-          console.log('webtty stopped');
-        } else {
-          console.error(`webtty stop failed (status: ${res.status})`);
-          process.exit(1);
-        }
-      } catch {
+      if (!(await isServerRunning())) {
         console.log('webtty is not running');
+        return;
+      }
+      const ok = await stopServer();
+      if (ok) {
+        console.log('webtty stopped');
+      } else {
+        console.error('webtty stop failed');
+        process.exit(1);
       }
     });
 
@@ -155,4 +155,19 @@ export function registerCommands(program: Command): void {
         process.exit(1);
       }
     });
+
+  program
+    .command('restart')
+    .description('Restart the webtty server')
+    .action(async () => {
+      if (await isServerRunning()) {
+        const ok = await stopServer();
+        if (!ok) {
+          console.error('webtty: failed to stop server');
+          process.exit(1);
+        }
+      }
+      await startServer();
+      console.log('webtty restarted');
+    });
 }
diff --git a/src/cli/http.test.ts b/src/cli/http.test.ts
new file mode 100644
index 0000000..c206969
--- /dev/null
+++ b/src/cli/http.test.ts
@@ -0,0 +1,206 @@
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test';
+import fs from 'node:fs';
+
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+describe('isServerRunning', () => {
+  test('returns true when GET /api/sessions succeeds', async () => {
+    globalThis.fetch = mock(
+      async () => new Response('[]', { status: 200 }),
+    ) as unknown as typeof fetch;
+
+    const { isServerRunning } = await import('./http');
+    expect(await isServerRunning()).toBe(true);
+  });
+
+  test('returns false when fetch throws', async () => {
+    globalThis.fetch = mock(async () => {
+      throw new Error('connection refused');
+    }) as unknown as typeof fetch;
+
+    const { isServerRunning } = await import('./http');
+    expect(await isServerRunning()).toBe(false);
+  });
+});
+
+describe('stopServer', () => {
+  test('returns true when server stops after POST succeeds', async () => {
+    let callCount = 0;
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      if (init?.method === 'POST') return new Response('stopping', { status: 200 });
+      callCount++;
+      if (callCount >= 2) throw new Error('connection refused');
+      return new Response('[]', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer()).toBe(true);
+  });
+
+  test('returns false when POST to stop endpoint fails', async () => {
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      if (init?.method === 'POST') return new Response('error', { status: 500 });
+      return new Response('[]', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer()).toBe(false);
+  });
+
+  test('returns false when fetch throws', async () => {
+    globalThis.fetch = mock(async () => {
+      throw new Error('connection refused');
+    }) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer()).toBe(false);
+  });
+
+  test('returns false when server does not come down within timeout', async () => {
+    globalThis.fetch = mock(
+      async () => new Response('[]', { status: 200 }),
+    ) as unknown as typeof fetch;
+
+    const { stopServer } = await import('./http');
+    expect(await stopServer('http://127.0.0.1:1', 100)).toBe(false);
+  });
+});
+
+describe('startServer', () => {
+  test('exits with error when server entry not found', async () => {
+    const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(false);
+    const exitSpy = spyOn(process, 'exit').mockImplementation((() => {}) as () => never);
+    const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
+
+    const { startServer } = await import('./http');
+    await startServer();
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('server entry not found'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    existsSpy.mockRestore();
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test('spawns server and resolves when it becomes reachable', async () => {
+    const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(true);
+    const fakeChild = { unref: mock(() => {}) };
+    const spawnMock = mock(() => fakeChild);
+
+    let calls = 0;
+    globalThis.fetch = mock(async () => {
+      calls++;
+      if (calls < 3) throw new Error('not yet');
+      return new Response('[]', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const { startServer } = await import('./http');
+    await startServer(10000, spawnMock as never);
+
+    expect(calls).toBeGreaterThanOrEqual(3);
+    expect(fakeChild.unref).toHaveBeenCalled();
+
+    existsSpy.mockRestore();
+  });
+
+  test('exits with error when server does not start within timeout', async () => {
+    const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(true);
+    const spawnMock = mock(() => ({ unref: () => {} }));
+    const exitSpy = spyOn(process, 'exit').mockImplementation((() => {}) as () => never);
+    const errorSpy = spyOn(console, 'error').mockImplementation(() => {});
+
+    globalThis.fetch = mock(async () => {
+      throw new Error('not yet');
+    }) as unknown as typeof fetch;
+
+    const { startServer } = await import('./http');
+    await startServer(100, spawnMock as never);
+
+    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('server did not start in time'));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    existsSpy.mockRestore();
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});
+
+describe('openBrowser', () => {
+  test('does nothing when WEBTTY_NO_OPEN=1', async () => {
+    const origEnv = process.env.WEBTTY_NO_OPEN;
+    process.env.WEBTTY_NO_OPEN = '1';
+    const spawnMock = mock(() => ({ unref: () => {} }));
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).not.toHaveBeenCalled();
+
+    process.env.WEBTTY_NO_OPEN = origEnv;
+  });
+
+  test('spawns open on darwin', async () => {
+    const origNodeEnv = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
+    const origPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true });
+    const spawnMock = mock(() => ({ unref: () => {} }));
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).toHaveBeenCalledWith(
+      'open',
+      ['http://localhost:2346/s/main'],
+      expect.anything(),
+    );
+
+    Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+    process.env.NODE_ENV = origNodeEnv;
+  });
+
+  test('spawns xdg-open on linux', async () => {
+    const origNodeEnv = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
+    const origPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'linux', configurable: true });
+    const spawnMock = mock(() => ({ unref: () => {} }));
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).toHaveBeenCalledWith(
+      'xdg-open',
+      ['http://localhost:2346/s/main'],
+      expect.anything(),
+    );
+
+    Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+    process.env.NODE_ENV = origNodeEnv;
+  });
+
+  test('spawns cmd.exe on win32', async () => {
+    const origNodeEnv = process.env.NODE_ENV;
+    delete process.env.NODE_ENV;
+    const origPlatform = process.platform;
+    Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+    const spawnMock = mock(() => ({ unref: () => {} }));
+
+    const { openBrowser } = await import('./http');
+    openBrowser('http://localhost:2346/s/main', spawnMock as never);
+    expect(spawnMock).toHaveBeenCalledWith(
+      'cmd.exe',
+      expect.arrayContaining(['start']),
+      expect.anything(),
+    );
+
+    Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true });
+    process.env.NODE_ENV = origNodeEnv;
+  });
+});
diff --git a/src/cli/http.ts b/src/cli/http.ts
index 7724858..a10e5ea 100644
--- a/src/cli/http.ts
+++ b/src/cli/http.ts
@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import * as childProcess from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -18,11 +18,7 @@ export async function isServerRunning(): Promise<boolean> {
   }
 }
 
-export async function startServer(): Promise<void> {
-  // When running from source (e.g. `bun run src/cli/index.ts` during development),
-  // __filename ends with .ts and Bun is the runtime, so we can point at the .ts
-  // server entry directly. Built output always lands in .js, so Node is never
-  // asked to execute TypeScript. In production isTs is always false.
+export async function startServer(timeoutMs = 10000, _spawn = childProcess.spawn): Promise<void> {
   const isBun = typeof (globalThis as Record<string, unknown>).Bun !== 'undefined';
   const isTs = isBun && __filename.endsWith('.ts');
   const serverEntry = path.resolve(__dirname, isTs ? '../server/index.ts' : '../server/index.js');
@@ -30,16 +26,14 @@ export async function startServer(): Promise<void> {
     console.error(`webtty: server entry not found at ${serverEntry}`);
     process.exit(1);
   }
-  // Reuse the current runtime (bun, node, etc.) to spawn the server so the
-  // server always runs under the same runtime as the CLI.
-  const child = spawn(process.execPath, [serverEntry], {
+  const child = _spawn(process.execPath, [serverEntry], {
     detached: true,
     stdio: 'ignore',
     env: { ...process.env, PORT: String(PORT) },
   });
   child.unref();
 
-  const deadline = Date.now() + 10000;
+  const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await isServerRunning()) return;
     await new Promise((r) => setTimeout(r, 100));
@@ -48,12 +42,28 @@ export async function startServer(): Promise<void> {
   process.exit(1);
 }
 
-export function openBrowser(url: string): void {
+export async function stopServer(baseUrl: string = BASE_URL, timeoutMs = 5000): Promise<boolean> {
+  try {
+    const res = await fetch(`${baseUrl}/api/server/stop`, { method: 'POST' });
+    if (!res.ok) return false;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (!(await isServerRunning())) return true;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export function openBrowser(url: string, _spawn = childProcess.spawn): void {
   if (process.env.WEBTTY_NO_OPEN === '1') return;
+  if (process.env.NODE_ENV === 'test') return;
   if (process.platform === 'win32') {
-    spawn('cmd.exe', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+    _spawn('cmd.exe', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
   } else {
     const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
-    spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
+    _spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
   }
 }
diff --git a/src/config.test.ts b/src/config.test.ts
new file mode 100644
index 0000000..c8aad44
--- /dev/null
+++ b/src/config.test.ts
@@ -0,0 +1,167 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_CONFIG, DEFAULT_THEME, loadConfig, saveConfig } from './config';
+
+let tmpDir: string;
+let configPath: string;
+let homedirSpy: ReturnType<typeof spyOn>;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webtty-config-test-'));
+  configPath = path.join(tmpDir, '.config', 'webtty', 'config.json');
+  homedirSpy = spyOn(os, 'homedir').mockReturnValue(tmpDir);
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+  homedirSpy.mockRestore();
+});
+
+describe('saveConfig', () => {
+  test('creates the config directory if it does not exist', () => {
+    saveConfig(DEFAULT_CONFIG);
+    expect(fs.existsSync(path.dirname(configPath))).toBe(true);
+  });
+
+  test('writes valid JSON', () => {
+    saveConfig(DEFAULT_CONFIG);
+    const raw = fs.readFileSync(configPath, 'utf8');
+    expect(() => JSON.parse(raw)).not.toThrow();
+  });
+
+  test('written file contains port and host', () => {
+    saveConfig(DEFAULT_CONFIG);
+    const raw = fs.readFileSync(configPath, 'utf8');
+    expect(raw).toContain('"port"');
+    expect(raw).toContain('"host"');
+  });
+});
+
+describe('loadConfig — first run', () => {
+  test('creates the config file when it does not exist', () => {
+    expect(fs.existsSync(configPath)).toBe(false);
+    loadConfig();
+    expect(fs.existsSync(configPath)).toBe(true);
+  });
+
+  test('returns config that equals DEFAULT_CONFIG after first run', () => {
+    const config = loadConfig();
+    expect(config.port).toBe(DEFAULT_CONFIG.port);
+    expect(config.host).toBe(DEFAULT_CONFIG.host);
+    expect(config.cols).toBe(DEFAULT_CONFIG.cols);
+    expect(config.rows).toBe(DEFAULT_CONFIG.rows);
+    expect(config.fontSize).toBe(DEFAULT_CONFIG.fontSize);
+    expect(config.cursorBlink).toBe(DEFAULT_CONFIG.cursorBlink);
+    expect(config.scrollback).toBe(DEFAULT_CONFIG.scrollback);
+    expect(config.theme).toEqual(DEFAULT_CONFIG.theme);
+  });
+
+  test('warns and returns defaults when write fails', () => {
+    const configDir = path.dirname(configPath);
+    fs.mkdirSync(path.dirname(configDir), { recursive: true });
+    fs.writeFileSync(configDir, 'not-a-dir');
+
+    const warned: string[] = [];
+    const origWarn = console.warn;
+    console.warn = (...args: unknown[]) => warned.push(args.join(' '));
+
+    let config: ReturnType<typeof loadConfig> | undefined;
+    expect(() => {
+      config = loadConfig();
+    }).not.toThrow();
+
+    console.warn = origWarn;
+
+    expect(warned.some((w) => w.includes('webtty:'))).toBe(true);
+    expect(config?.port).toBe(DEFAULT_CONFIG.port);
+  });
+});
+
+describe('loadConfig — reads and merges', () => {
+  function writeConfig(content: string) {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, content, 'utf8');
+  }
+
+  test('returns full defaults when file has no overrides', () => {
+    writeConfig('{}');
+    const config = loadConfig();
+    expect(config.port).toBe(DEFAULT_CONFIG.port);
+    expect(config.cols).toBe(DEFAULT_CONFIG.cols);
+    expect(config.theme).toEqual(DEFAULT_THEME);
+  });
+
+  test('overrides port when set in file', () => {
+    writeConfig(JSON.stringify({ port: 9999 }));
+    expect(loadConfig().port).toBe(9999);
+  });
+
+  test('overrides host when set in file', () => {
+    writeConfig(JSON.stringify({ host: '0.0.0.0' }));
+    expect(loadConfig().host).toBe('0.0.0.0');
+  });
+
+  test('overrides shell when set in file', () => {
+    writeConfig(JSON.stringify({ shell: '/bin/zsh' }));
+    expect(loadConfig().shell).toBe('/bin/zsh');
+  });
+
+  test('overrides fontSize and fontFamily when set in file', () => {
+    writeConfig(JSON.stringify({ fontSize: 18, fontFamily: 'Menlo' }));
+    const config = loadConfig();
+    expect(config.fontSize).toBe(18);
+    expect(config.fontFamily).toBe('Menlo');
+  });
+
+  test('overrides cursorBlink when set to false', () => {
+    writeConfig(JSON.stringify({ cursorBlink: false }));
+    expect(loadConfig().cursorBlink).toBe(false);
+  });
+
+  test('overrides cols and rows when set in file', () => {
+    writeConfig(JSON.stringify({ cols: 120, rows: 40 }));
+    const config = loadConfig();
+    expect(config.cols).toBe(120);
+    expect(config.rows).toBe(40);
+  });
+
+  test('overrides scrollback when set in file', () => {
+    writeConfig(JSON.stringify({ scrollback: 1024 }));
+    expect(loadConfig().scrollback).toBe(1024);
+  });
+
+  test('merges partial theme over DEFAULT_THEME', () => {
+    writeConfig(JSON.stringify({ theme: { background: '#000000' } }));
+    const config = loadConfig();
+    expect(config.theme.background).toBe('#000000');
+    expect(config.theme.foreground).toBe(DEFAULT_THEME.foreground);
+    expect(config.theme.red).toBe(DEFAULT_THEME.red);
+  });
+
+  test('ignores unknown keys', () => {
+    writeConfig(JSON.stringify({ unknownKey: 'value', port: 1234 }));
+    const config = loadConfig();
+    expect(config.port).toBe(1234);
+    expect((config as unknown as Record<string, unknown>).unknownKey).toBeUndefined();
+  });
+
+  test('ignores keys with wrong types and falls back to defaults', () => {
+    writeConfig(JSON.stringify({ port: 'not-a-number', cols: true, host: 42 }));
+    const config = loadConfig();
+    expect(config.port).toBe(DEFAULT_CONFIG.port);
+    expect(config.cols).toBe(DEFAULT_CONFIG.cols);
+    expect(config.host).toBe(DEFAULT_CONFIG.host);
+  });
+
+  test('throws on invalid JSON', () => {
+    writeConfig('{ not valid json }');
+    expect(() => loadConfig()).toThrow(/invalid JSON/);
+  });
+
+  test('throws with webtty: prefix in message on read error', () => {
+    fs.mkdirSync(configPath, { recursive: true });
+    expect(() => loadConfig()).toThrow(/webtty:/);
+  });
+});
diff --git a/src/config.ts b/src/config.ts
new file mode 100644
index 0000000..aa1bb85
--- /dev/null
+++ b/src/config.ts
@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export interface Theme {
+  background?: string;
+  foreground?: string;
+  cursor?: string;
+  selection?: string;
+  black?: string;
+  red?: string;
+  green?: string;
+  yellow?: string;
+  blue?: string;
+  purple?: string;
+  cyan?: string;
+  white?: string;
+  brightBlack?: string;
+  brightRed?: string;
+  brightGreen?: string;
+  brightYellow?: string;
+  brightBlue?: string;
+  brightPurple?: string;
+  brightCyan?: string;
+  brightWhite?: string;
+}
+
+export interface Config {
+  port: number;
+  host: string;
+  shell: string;
+  term: string;
+  colorTerm: string;
+  scrollback: number;
+  cols: number;
+  rows: number;
+  fontSize: number;
+  fontFamily: string;
+  cursorBlink: boolean;
+  theme: Theme;
+}
+
+function getConfigPath(): string {
+  return path.join(os.homedir(), '.config', 'webtty', 'config.json');
+}
+
+export const DEFAULT_THEME: Theme = {
+  background: '#000000',
+  foreground: '#CCCCCC',
+  cursor: '#FFFFFF',
+  selection: '#FFFFFF',
+  black: '#0C0C0C',
+  red: '#C50F1F',
+  green: '#13A10E',
+  yellow: '#C19C00',
+  blue: '#0037DA',
+  purple: '#881798',
+  cyan: '#3A96DD',
+  white: '#CCCCCC',
+  brightBlack: '#767676',
+  brightRed: '#E74856',
+  brightGreen: '#16C60C',
+  brightYellow: '#F9F1A5',
+  brightBlue: '#3B78FF',
+  brightPurple: '#B4009E',
+  brightCyan: '#61D6D6',
+  brightWhite: '#F2F2F2',
+};
+
+export const DEFAULT_CONFIG: Config = {
+  port: 2346,
+  host: '127.0.0.1',
+  shell:
+    process.platform === 'win32'
+      ? (process.env.COMSPEC ?? 'cmd.exe')
+      : (process.env.SHELL ?? '/bin/bash'),
+  term: process.env.TERM ?? 'xterm-256color',
+  colorTerm: 'truecolor',
+  scrollback: 256 * 1024,
+  cols: 80,
+  rows: 24,
+  fontSize: 13,
+  fontFamily: "Menlo, Consolas, 'DejaVu Sans Mono', monospace",
+  cursorBlink: true,
+  theme: DEFAULT_THEME,
+};
+
+export function loadConfig(): Config {
+  if (!fs.existsSync(getConfigPath())) {
+    try {
+      saveConfig(DEFAULT_CONFIG);
+    } catch (err) {
+      console.warn(
+        `webtty: failed to write default config to ${getConfigPath()}: ${(err as Error).message}`,
+      );
+      return { ...DEFAULT_CONFIG };
+    }
+  }
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(getConfigPath(), 'utf8');
+  } catch (err) {
+    throw new Error(
+      `webtty: failed to read config at ${getConfigPath()}: ${(err as Error).message}`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`webtty: invalid JSON in config file ${getConfigPath()}`);
+  }
+
+  const p = parsed as Partial<Config>;
+  return {
+    ...DEFAULT_CONFIG,
+    ...(typeof p.port === 'number' && { port: p.port }),
+    ...(typeof p.host === 'string' && { host: p.host }),
+    ...(typeof p.shell === 'string' && { shell: p.shell }),
+    ...(typeof p.term === 'string' && { term: p.term }),
+    ...(typeof p.colorTerm === 'string' && { colorTerm: p.colorTerm }),
+    ...(typeof p.scrollback === 'number' && { scrollback: p.scrollback }),
+    ...(typeof p.cols === 'number' && { cols: p.cols }),
+    ...(typeof p.rows === 'number' && { rows: p.rows }),
+    ...(typeof p.fontSize === 'number' && { fontSize: p.fontSize }),
+    ...(typeof p.fontFamily === 'string' && { fontFamily: p.fontFamily }),
+    ...(typeof p.cursorBlink === 'boolean' && { cursorBlink: p.cursorBlink }),
+    ...(p.theme && typeof p.theme === 'object' && { theme: { ...DEFAULT_THEME, ...p.theme } }),
+  };
+}
+
+export function saveConfig(_config: Config): void {
+  fs.mkdirSync(path.dirname(getConfigPath()), { recursive: true });
+  const content = JSON.stringify(
+    {
+      port: DEFAULT_CONFIG.port,
+      host: DEFAULT_CONFIG.host,
+    },
+    null,
+    2,
+  );
+  fs.writeFileSync(getConfigPath(), content, 'utf8');
+}
diff --git a/src/pty/bun.ts b/src/pty/bun.ts
index 31df2eb..de9c75e 100644
--- a/src/pty/bun.ts
+++ b/src/pty/bun.ts
@@ -1,7 +1,13 @@
 import { homedir } from 'node:os';
 import type { PtyProcess } from './types';
 
-export function spawn(shell: string, cols: number, rows: number): PtyProcess {
+export function spawn(
+  shell: string,
+  cols: number,
+  rows: number,
+  term: string,
+  colorTerm: string,
+): PtyProcess {
   let onDataCb: ((data: string) => void) | undefined;
   let onExitCb: ((e: { exitCode: number }) => void) | undefined;
 
@@ -14,7 +20,7 @@ export function spawn(shell: string, cols: number, rows: number): PtyProcess {
       },
     },
     cwd: homedir(),
-    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+    env: { ...process.env, TERM: term, COLORTERM: colorTerm },
   });
 
   proc.exited.then((exitCode) => {
diff --git a/src/pty/index.ts b/src/pty/index.ts
index ae2bb65..4d35d91 100644
--- a/src/pty/index.ts
+++ b/src/pty/index.ts
@@ -7,10 +7,12 @@ const { spawn: _spawn } = await (isBun ? import('./bun') : import('./node'));
 
 export const spawn = _spawn;
 
-export function spawnForSession(cols: number, rows: number) {
-  const shell =
-    process.platform === 'win32'
-      ? (process.env.COMSPEC ?? 'cmd.exe')
-      : (process.env.SHELL ?? '/bin/bash');
-  return _spawn(shell, cols, rows);
+export function spawnForSession(
+  cols: number,
+  rows: number,
+  shell: string,
+  term: string,
+  colorTerm: string,
+) {
+  return _spawn(shell, cols, rows, term, colorTerm);
 }
diff --git a/src/pty/node.ts b/src/pty/node.ts
index 8eae6db..4dbaf01 100644
--- a/src/pty/node.ts
+++ b/src/pty/node.ts
@@ -2,13 +2,19 @@ import { homedir } from 'node:os';
 import nodePty from '@lydell/node-pty';
 import type { PtyProcess } from './types';
 
-export function spawn(shell: string, cols: number, rows: number): PtyProcess {
+export function spawn(
+  shell: string,
+  cols: number,
+  rows: number,
+  term: string,
+  colorTerm: string,
+): PtyProcess {
   const ptyProc = nodePty.spawn(shell, [], {
-    name: 'xterm-256color',
+    name: term,
     cols,
     rows,
     cwd: homedir(),
-    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+    env: { ...process.env, TERM: term, COLORTERM: colorTerm },
   });
 
   return {
diff --git a/src/server/client.test.ts b/src/server/client.test.ts
index a4a15ea..0e8d37d 100644
--- a/src/server/client.test.ts
+++ b/src/server/client.test.ts
@@ -1,31 +1,75 @@
 import { describe, expect, test } from 'bun:test';
+import { DEFAULT_CONFIG } from '../config';
 import { render } from './client';
 
 describe('clientShell', () => {
   test('returns valid HTML document', () => {
-    const html = render('my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('<!doctype html>');
     expect(html).toContain('<html');
     expect(html).toContain('</html>');
   });
 
   test('injects session id into title', () => {
-    const html = render('my-session');
-    expect(html).toContain('webtty — my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
+    expect(html).toContain('my-session | webtty');
   });
 
   test('injects session id as JS string literal', () => {
-    const html = render('my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('"my-session"');
   });
 
   test('JS string literal uses JSON.stringify so special chars are escaped', () => {
-    const html = render('my"session');
+    const html = render('my"session', DEFAULT_CONFIG);
     expect(html).toContain('"my\\"session"');
   });
 
   test('ws path uses session id', () => {
-    const html = render('my-session');
+    const html = render('my-session', DEFAULT_CONFIG);
     expect(html).toContain('/ws/');
   });
+
+  test('injects fontSize into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, fontSize: 20 });
+    expect(html).toContain('fontSize: 20');
+  });
+
+  test('injects fontFamily into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, fontFamily: 'Menlo' });
+    expect(html).toContain('fontFamily: "Menlo"');
+  });
+
+  test('injects cols and rows into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, cols: 120, rows: 40 });
+    expect(html).toContain('cols: 120');
+    expect(html).toContain('rows: 40');
+  });
+
+  test('injects cursorBlink into terminal options', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, cursorBlink: false });
+    expect(html).toContain('cursorBlink: false');
+  });
+
+  test('injects scrollback as line count derived from bytes', () => {
+    const html = render('s', { ...DEFAULT_CONFIG, scrollback: 8000 });
+    expect(html).toContain(`scrollback: ${Math.ceil(8000 / 80)}`);
+  });
+
+  test('injects theme background color into CSS', () => {
+    const html = render('s', {
+      ...DEFAULT_CONFIG,
+      theme: { ...DEFAULT_CONFIG.theme, background: '#FF0000' },
+    });
+    expect(html).toContain('#FF0000');
+  });
+
+  test('injects full theme object into terminal options', () => {
+    const html = render('s', {
+      ...DEFAULT_CONFIG,
+      theme: { ...DEFAULT_CONFIG.theme, foreground: '#AABBCC' },
+    });
+    expect(html).toContain('"foreground"');
+    expect(html).toContain('#AABBCC');
+  });
 });
diff --git a/src/server/client.ts b/src/server/client.ts
index 2553df0..199ca0d 100644
--- a/src/server/client.ts
+++ b/src/server/client.ts
@@ -1,14 +1,19 @@
-export function render(sessionId: string): string {
+import type { Config } from '../config';
+
+export function render(sessionId: string, config: Config): string {
+  const theme = config.theme;
+  const themeJson = JSON.stringify(theme, null, 8).replace(/^/gm, '        ').trimStart();
   return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>webtty — ${sessionId}</title>
+    <title>${sessionId} | webtty</title>
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect x='5' y='5' width='90' height='90' rx='18' fill='white'/><text x='8' y='73' font-size='58' font-family='monospace' font-weight='bold' fill='%23161b22'>>_</text></svg>">
     <style>
       * { margin: 0; padding: 0; box-sizing: border-box; }
 
-      html, body, #terminal { width: 100%; height: 100%; overflow: hidden; background: #282A36; }
+      html, body, #terminal { width: 100%; height: 100%; overflow: hidden; background: ${theme.background ?? '#282A36'}; }
 
       #terminal canvas { display: block; }
     </style>
@@ -21,34 +26,13 @@ export function render(sessionId: string): string {
 
       await init();
       const term = new Terminal({
-        cols: 80,
-        rows: 24,
-        cursorBlink: true,
-        fontSize: 14,
-        fontFamily: "'FiraMono Nerd Font', Menlo, Monaco, 'Courier New', monospace",
-        scrollback: 10000,
-        theme: {
-          background:   '#282A36',
-          foreground:   '#F8F8F2',
-          cursor:       '#F8F8F2',
-          selection:    '#44475A',
-          black:        '#21222C',
-          red:          '#FF5555',
-          green:        '#50FA7B',
-          yellow:       '#F1FA8C',
-          blue:         '#BD93F9',
-          purple:       '#FF79C6',
-          cyan:         '#8BE9FD',
-          white:        '#F8F8F2',
-          brightBlack:  '#6272A4',
-          brightRed:    '#FF6E6E',
-          brightGreen:  '#69FF94',
-          brightYellow: '#FFFFA5',
-          brightBlue:   '#D6ACFF',
-          brightPurple: '#FF92DF',
-          brightCyan:   '#A4FFFF',
-          brightWhite:  '#FFFFFF',
-        },
+        cols: ${config.cols},
+        rows: ${config.rows},
+        cursorBlink: ${config.cursorBlink},
+        fontSize: ${config.fontSize},
+        fontFamily: ${JSON.stringify(config.fontFamily)},
+        scrollback: ${Math.ceil(config.scrollback / 80)},
+        theme: ${themeJson},
       });
 
       const fitAddon = new FitAddon();
@@ -67,8 +51,11 @@ export function render(sessionId: string): string {
         const wsUrl = protocol + '//' + window.location.host + '/ws/' + sessionId + '?cols=' + term.cols + '&rows=' + term.rows;
         ws = new WebSocket(wsUrl);
 
+        const DIM = '\\x1b[2m', YELLOW = '\\x1b[1;33m', ITALIC = '\\x1b[3m', RESET = '\\x1b[0m';
+        const tag = DIM + '[' + RESET + ' ' + YELLOW + 'webtty' + RESET + ' ' + DIM + ']' + RESET;
+        const msg = (text) => '\\r\\n' + tag + ' ' + DIM + ITALIC + text + RESET + '\\r\\n';
+
         ws.onopen = () => {
-          console.log('[webtty] connected to session ' + sessionId);
           ws.send(JSON.stringify({ type: 'resize', cols: term.cols, rows: term.rows }));
         };
 
@@ -78,22 +65,21 @@ export function render(sessionId: string): string {
 
         ws.onclose = (event) => {
           if (event.code === 4001) {
-            term.write('\\r\\n\\x1b[31mSession removed.\\x1b[0m\\r\\n');
+            term.write(msg('Session removed.'));
             setTimeout(() => window.close(), 500);
             return;
           }
           if (event.code === 1001) {
-            term.write('\\r\\n\\x1b[33mServer stopped.\\x1b[0m\\r\\n');
+            term.write(msg('Server stopped.'));
             setTimeout(() => window.close(), 500);
             return;
           }
-          console.log('[webtty] disconnected, reconnecting in 2s...');
-          term.write('\\r\\n\\x1b[31mConnection closed. Reconnecting in 2s...\\x1b[0m\\r\\n');
+          term.write(msg('Connection lost. Reconnecting in 2s...'));          
           setTimeout(connect, 2000);
         };
 
         ws.onerror = () => {
-          console.error('[webtty] websocket error');
+          term.write(msg('WebSocket error.'));
         };
       }
 
diff --git a/src/server/index.ts b/src/server/index.ts
index 68ded18..ef10085 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -1,32 +1,17 @@
 import http from 'node:http';
+import { loadConfig } from '../config';
 import { handleRequest } from './routes';
-import { sessionRegistry } from './session';
 import { findGhosttyWeb } from './static';
-import { createWebSocketServer } from './websocket';
+import { closeAllSessions, createWebSocketServer } from './websocket';
 
-const HTTP_PORT = Number(process.env.PORT) || 2346;
+const config = loadConfig();
+const HTTP_PORT = Number(process.env.PORT) || config.port;
+const HTTP_HOST = config.host;
 
 const { distPath, wasmPath } = findGhosttyWeb();
 
-const httpServer = http.createServer((req, res) => {
-  handleRequest(req, res, distPath, wasmPath, () => {
-    for (const session of sessionRegistry.values()) {
-      session.pty?.kill();
-      for (const client of session.clients) client.close(1001, 'server stopped');
-    }
-    wss.close();
-    httpServer.close(() => process.exit(0));
-  });
-});
-
-const wss = createWebSocketServer(httpServer);
-
-process.on('SIGINT', () => {
-  console.log('\n\nShutting down...');
-  for (const session of sessionRegistry.values()) {
-    session.pty?.kill();
-    for (const client of session.clients) client.close(1001, 'server stopped');
-  }
+function shutdown() {
+  closeAllSessions();
   wss.close();
   const exit = () => process.exit(0);
   const shutdownTimeout = setTimeout(exit, 1000);
@@ -34,8 +19,19 @@ process.on('SIGINT', () => {
     clearTimeout(shutdownTimeout);
     exit();
   });
+}
+
+const httpServer = http.createServer((req, res) => {
+  handleRequest(req, res, distPath, wasmPath, shutdown);
+});
+
+const wss = createWebSocketServer(httpServer);
+
+process.on('SIGINT', () => {
+  console.log('\n\nShutting down...');
+  shutdown();
 });
 
-httpServer.listen(HTTP_PORT, '127.0.0.1', () => {
-  console.log(`listening on http://127.0.0.1:${HTTP_PORT}`);
+httpServer.listen(HTTP_PORT, HTTP_HOST, () => {
+  console.log(`listening on http://${HTTP_HOST}:${HTTP_PORT}`);
 });
diff --git a/src/server/routes.ts b/src/server/routes.ts
index c24676a..c47fd39 100644
--- a/src/server/routes.ts
+++ b/src/server/routes.ts
@@ -1,5 +1,6 @@
 import type http from 'node:http';
 import path from 'node:path';
+import { loadConfig } from '../config';
 import { render } from './client';
 import {
   createSession,
@@ -11,6 +12,7 @@ import {
   setLastUsedId,
 } from './session';
 import { serveFile } from './static';
+import { closeSession } from './websocket';
 
 const MAX_BODY = 64 * 1024;
 
@@ -170,8 +172,7 @@ export async function handleRequest(
       }
       sessionRegistry.delete(id);
       if (lastUsedId === id) setLastUsedId(null);
-      for (const client of session.clients) client.close(4001, 'session deleted');
-      session.pty?.kill();
+      closeSession(session);
       res.writeHead(204);
       res.end();
       return;
@@ -198,7 +199,7 @@ export async function handleRequest(
       return;
     }
     res.writeHead(200, { 'Content-Type': 'text/html' });
-    res.end(render(id));
+    res.end(render(id, loadConfig()));
     return;
   }
 
diff --git a/src/server/session.test.ts b/src/server/session.test.ts
index a4c920e..4405594 100644
--- a/src/server/session.test.ts
+++ b/src/server/session.test.ts
@@ -1,5 +1,13 @@
 import { beforeEach, describe, expect, test } from 'bun:test';
-import { createSession, generateId, isValidId, sessionRegistry, sessionToJson } from './session';
+import {
+  createSession,
+  generateId,
+  isValidId,
+  lastUsedId,
+  sessionRegistry,
+  sessionToJson,
+  setLastUsedId,
+} from './session';
 
 beforeEach(() => {
   sessionRegistry.clear();
@@ -83,3 +91,16 @@ describe('sessionToJson', () => {
     expect(typeof json.createdAt).toBe('number');
   });
 });
+
+describe('setLastUsedId', () => {
+  test('updates lastUsedId to the given value', () => {
+    setLastUsedId('my-session');
+    expect(lastUsedId).toBe('my-session');
+  });
+
+  test('accepts null to clear lastUsedId', () => {
+    setLastUsedId('my-session');
+    setLastUsedId(null);
+    expect(lastUsedId).toBeNull();
+  });
+});
diff --git a/src/server/session.ts b/src/server/session.ts
index 61e6c55..d03d7d4 100644
--- a/src/server/session.ts
+++ b/src/server/session.ts
@@ -1,8 +1,6 @@
 import type { WebSocket as WS } from 'ws';
 import type { PtyProcess } from '../pty';
 
-export const SCROLLBACK_MAX = 256 * 1024;
-
 export interface Session {
   id: string;
   createdAt: number;
diff --git a/src/server/websocket.test.ts b/src/server/websocket.test.ts
index 8fb9aee..4cb5d14 100644
--- a/src/server/websocket.test.ts
+++ b/src/server/websocket.test.ts
@@ -3,6 +3,10 @@ import { type ChildProcess, spawn } from 'node:child_process';
 import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+
+const ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+const stripAnsi = (s: string) => s.replace(ANSI_RE, '');
+
 import { WebSocket } from 'ws';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -100,7 +104,7 @@ describe('websocket', () => {
     await waitForMessages(messages, 1);
     await closeWs(ws);
 
-    expect(messages.join('')).toContain('Welcome to webtty');
+    expect(stripAnsi(messages.join(''))).toContain('webtty');
   });
 
   test('reconnect replays scrollback without banner', async () => {
@@ -122,9 +126,9 @@ describe('websocket', () => {
     await waitForMessages(m2, 1);
     await closeWs(ws2);
 
-    const replay = m2.join('');
-    expect(replay).toContain('Welcome to webtty');
-    expect(replay.indexOf('Welcome to webtty')).toBe(replay.lastIndexOf('Welcome to webtty'));
+    const replay = stripAnsi(m2.join(''));
+    expect(replay).toContain('webtty');
+    expect(replay.indexOf('Terminal UI')).toBe(replay.lastIndexOf('Terminal UI'));
   });
 
   test('multiple clients receive same PTY output', async () => {
diff --git a/src/server/websocket.ts b/src/server/websocket.ts
index 4932743..f97060b 100644
--- a/src/server/websocket.ts
+++ b/src/server/websocket.ts
@@ -1,8 +1,74 @@
 import type http from 'node:http';
 import type { WebSocket as WS } from 'ws';
 import { WebSocketServer } from 'ws';
+import { loadConfig } from '../config';
 import { spawnForSession } from '../pty';
-import { SCROLLBACK_MAX, sessionRegistry, setLastUsedId } from './session';
+import type { Session } from './session';
+import { sessionRegistry, setLastUsedId } from './session';
+
+const WS_CLOSE = {
+  SERVER_STOPPED: 1001 as const, // RFC 6455: server going away
+  BAD_REQUEST: 1008 as const, // RFC 6455: policy violation / bad data
+  SESSION_GONE: 4001 as const, // app-level: session deleted or shell exited
+} as const;
+
+function closeClients(session: Session, code: number, reason: string): void {
+  session.pty?.kill();
+  for (const client of session.clients) client.close(code, reason);
+}
+
+export function closeSession(session: Session): void {
+  closeClients(session, WS_CLOSE.SESSION_GONE, 'session deleted');
+}
+
+export function closeAllSessions(): void {
+  for (const session of sessionRegistry.values()) {
+    closeClients(session, WS_CLOSE.SERVER_STOPPED, 'server stopped');
+  }
+}
+
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const ITALIC = '\x1b[3m';
+const YELLOW = '\x1b[1;33m';
+const CYAN = '\x1b[1;36m';
+
+const isBun = process.execPath.includes('bun');
+const PKG_RUNNER = isBun ? 'bunx' : 'npx';
+
+function sessionBanner(): string {
+  const W = 48;
+  const pipe = (content: string) => `${CYAN}║${RESET}${content}${CYAN}║${RESET}`;
+  const blank = pipe(' '.repeat(W));
+
+  const titleVis = ' [ webtty ]   Terminal UI in the browser';
+  const titleStr = ` ${DIM}[${RESET} ${BOLD}${YELLOW}webtty${RESET} ${DIM}]   Terminal UI in the browser${RESET}`;
+  const titleLine = pipe(titleStr + ' '.repeat(W - titleVis.length));
+
+  const cmd = `${PKG_RUNNER} webtty help`;
+  const helpVis = ` Run \`${cmd}\` for more information.`;
+  const helpStr = ` ${DIM}Run \`${RESET}${ITALIC}${cmd}${RESET}${DIM}\` for more information.${RESET}`;
+  const helpLine = pipe(helpStr + ' '.repeat(W - helpVis.length));
+
+  return [
+    `${CYAN}╔${'═'.repeat(W)}╗${RESET}`,
+    '\r\n',
+    blank,
+    '\r\n',
+    titleLine,
+    '\r\n',
+    blank,
+    '\r\n',
+    helpLine,
+    '\r\n',
+    blank,
+    '\r\n',
+    `${CYAN}╚${'═'.repeat(W)}╝${RESET}`,
+    '\r\n',
+    '\r\n',
+  ].join('');
+}
 
 export function createWebSocketServer(httpServer: http.Server): WebSocketServer {
   const wss = new WebSocketServer({ noServer: true });
@@ -28,7 +94,7 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
     try {
       id = decodeURIComponent(wsMatch[1]);
     } catch {
-      ws.close(1008, 'Bad Request');
+      ws.close(WS_CLOSE.BAD_REQUEST, 'Bad Request');
       return;
     }
     const cols = Math.max(
@@ -41,23 +107,24 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
     );
 
     if (!sessionRegistry.has(id)) {
-      ws.close(4001, 'session deleted');
+      ws.close(WS_CLOSE.SESSION_GONE, 'session deleted');
       return;
     }
 
     const session = sessionRegistry.get(id);
     if (!session) {
-      ws.close(4001, 'session deleted');
+      ws.close(WS_CLOSE.SESSION_GONE, 'session deleted');
       return;
     }
     session.clients.add(ws);
     setLastUsedId(id);
 
     if (!session.pty) {
-      session.pty = spawnForSession(cols, rows);
+      const config = loadConfig();
+      session.pty = spawnForSession(cols, rows, config.shell, config.term, config.colorTerm);
 
       session.pty.onData((data: string) => {
-        session.scrollback = (session.scrollback + data).slice(-SCROLLBACK_MAX);
+        session.scrollback = (session.scrollback + data).slice(-config.scrollback);
         for (const client of session.clients) {
           if (client.readyState === client.OPEN) {
             client.send(data, { binary: false });
@@ -69,24 +136,13 @@ export function createWebSocketServer(httpServer: http.Server): WebSocketServer
         sessionRegistry.delete(session.id);
         for (const client of session.clients) {
           if (client.readyState === client.OPEN) {
-            client.close(4001, 'shell exited');
+            client.close(WS_CLOSE.SESSION_GONE, 'shell exited');
           }
         }
         session.pty = null;
       });
 
-      const C = '\x1b[1;36m';
-      const G = '\x1b[1;32m';
-      const Y = '\x1b[1;33m';
-      const R = '\x1b[0m';
-      const banner = [
-        `${C}╔══════════════════════════════════════════════════════════════╗${R}\r\n`,
-        `${C}║${R}  ${G}Welcome to webtty!${R}                                          ${C}║${R}\r\n`,
-        `${C}║${R}                                                              ${C}║${R}\r\n`,
-        `${C}║${R}  You have a real shell session with full PTY support.        ${C}║${R}\r\n`,
-        `${C}║${R}  Try: ${Y}ls${R}, ${Y}cd${R}, ${Y}top${R}, ${Y}vim${R}, or any command!                      ${C}║${R}\r\n`,
-        `${C}╚══════════════════════════════════════════════════════════════╝${R}\r\n\r\n`,
-      ].join('');
+      const banner = sessionBanner();
       ws.send(banner);
       session.scrollback = banner;
       session.pty.write('\n');