Live servers
A live server serves a local folder over HTTP or HTTPS for preview inside HarborClient — typically in an embedded live page browser tab. It is not meant for production hosting.
By default the server binds to loopback (127.0.0.1) and serves http://127.0.0.1:<port>. You can enable SSL for an https:// origin, and change the Host bind address (for example 0.0.0.0) to listen on the local network. Non-loopback binds expose the folder on the network — only use them on trusted networks. When the bind host is a wildcard (0.0.0.0 / ::), HarborClient still opens Live Page at a navigable loopback origin rather than http://0.0.0.0:….
Live servers are separate from live pages. A live page is a saved browser session; a live server is the local origin that can host the files that session loads.
Sidebar
Open the collection sidebar Servers rail to show Live Servers, then Server Logs, then Live pages.
Live Servers
When the list is empty, HarborClient shows No live servers.
Each row shows the server name, a subtitle with the root directory and either the running origin (which may be https://… when SSL is on), a fixed :port, or auto port, and a status dot (green when running, red when stopped).
| Action | How |
|---|---|
| New Live Server | Section header + control — opens the New Live Server footer panel |
| Start | Click a stopped row, or row menu → Start — starts the server and opens a browser tab at the open path (or remembered last URL when enabled) |
| Open | Click a running row, or row menu → Open — focuses or opens the bound browser tab |
| Edit | Row menu → Edit — opens the Edit Live Server footer panel |
| Logs | Row menu → Logs — opens the logs footer panel for the active session for that server, or the latest session if it is stopped |
| Copy ID | Row menu → Copy ID — copies the portable UUID |
| Copy to chat | Row menu → Copy to chat (when AI is available) — inserts an @live-server.<uuid> chat reference |
| Stop | Row menu → Stop — confirms, then stops the running instance |
| Delete | Row menu → Delete — removes the saved config (running instances are not stopped) |
Server Logs
When a live server starts, HarborClient adds a session row under Server Logs. When the list is empty, HarborClient shows No server logs.
Each row shows the server name, a subtitle with the start time and origin, and a green status dot while that instance is actively logging. Sessions stay in the list after Stop (without the green dot) until you clear them. They are kept in memory for the current app session only — quitting HarborClient discards them.
| Action | How |
|---|---|
| Open | Click a row — opens the logs footer panel for that start (including stopped sessions) |
| Clear | Section header erase control — confirms, then removes inactive sessions and empties buffers for any still-running (active) ones |
Create and edit
Creating or editing a live server opens a slide-up footer panel titled New Live Server or Edit Live Server. You can also start a new server from the app menu action that creates a live server.
The panel description: serve a local folder over HTTP(S) and open it in a Live Page. Settings are split into General, Headers, Routing, Proxy, Aliases, CORS, SSL, and Scripts tabs.
General
| Field | Description |
|---|---|
| Name | Display name in the sidebar |
| Root directory | Absolute path to the folder served as the document root. Use Browse to pick a directory |
| Port | Listen port (1–65535), or leave blank to use the next free port from 5500 |
| Open path | Path or file relative to the server origin (/, /docs/, preview.html). Empty becomes /; a leading / is added when missing. Used when starting or opening a fresh Live Page tab (unless Remember last URL applies) |
| Remember last URL | When on, navigations in the bound Live Page within the server origin persist the path (pathname + search + hash). The next start or new-tab open restores that path. Unchecking does not clear the stored path |
| Index files | Comma-separated ordered list of directory index filenames (for example index.html, index.htm). Empty falls back to index.html. Applied to the document root and aliases |
| Host | Bind address (default 127.0.0.1). Use 127.0.0.1 / localhost for this machine only, or 0.0.0.0 to listen on the local network. Non-loopback values show a warning that the folder will be exposed on trusted networks only |
| Aliases | Optional URL path → filesystem mappings — see Aliases |
| Reload page when files change | When enabled, HarborClient watches the root and reloads matching browser / Live Page tabs on change |
Dotfiles are not served.
Headers
The Headers tab sets custom response headers (for example Cache-Control, CSP, COOP, COEP). There are no built-in defaults — leave the list empty for none.
| Behavior | Detail |
|---|---|
| Rows | Each row has a header name, value, and enabled checkbox |
| Disabled / empty | Rows with an empty name or with enabled unchecked are not sent |
| When applied | After CORS middleware and before static files, including 404 responses |
Routing
The Routing tab maps request paths to a file or directory when nothing matched under aliases or the document root. Rules apply to GET and HEAD only. Use Add rule for each entry; order matters — the first matching enabled rule wins. Use Move up / Move down to reorder.
| Field | Description |
|---|---|
| Match | * for every remaining path, or a regex matched against the URL pathname (for example ^/docs/) |
| Target | File or directory path, absolute or relative to the server root (for example index.html or alt-root) |
| Enabled | When unchecked, the rule is ignored |
| Behavior | Detail |
|---|---|
| File target | Serves that file for matching requests |
| Directory target | Looks up the same request path under that directory; if missing, tries the next rule or returns 404 |
| SPA fallback | Match *, Target index.html — real assets still come from disk; only paths that missed static fall back (typical Vite / React history routing) |
| Skipped rules | Disabled rows and invalid regex patterns are skipped |
| vs Aliases | Aliases mount a path prefix before the document root. Routing runs after a static miss — use aliases for prefix mounts, routing for SPA fallback and soft remaps |
CORS
| Field | Description |
|---|---|
| Enable CORS | When on, HarborClient mounts CORS middleware (default on) |
| Origin | * for any origin, or a comma-separated list |
| Methods | Comma-separated HTTP methods, or * (default GET,HEAD,PUT,PATCH,POST,DELETE) |
| Allowed headers | *, blank (reflect requested headers), or a comma-separated list |
| Exposed headers | Headers browsers may read from the response: *, a comma-separated list, or blank (omit) |
| Max age | Preflight cache lifetime in seconds (for example 600). Blank omits the header |
| Allow credentials | When on, responses allow credentials. Incompatible with origin: * per the CORS specification |
Defaults match a permissive Express cors() setup with credentials off so origin: * stays valid. Exposed headers and max age stay empty until you set them.
SSL
HarborClient does not generate certificates. Supply your own PEM (or compatible) files when enabling HTTPS.
| Field | Description |
|---|---|
| Enable SSL | When on, the server listens with HTTPS using the configured certificate and private key |
| Certificate path | Absolute path to the certificate file. Use Browse (common extensions: .pem, .crt, .cert) |
| Private key path | Absolute path to the private key file. Use Browse (common extensions: .pem, .key) |
When SSL is enabled, both paths are required before the server can start. The running origin uses the https: scheme. Live Page allows certificate errors only for origins of currently running HTTPS live servers (for example self-signed certs) — this is not a global TLS disable.
Scripts
The Scripts tab runs JavaScript on incoming HTTP requests to the live server — the same isolated hc sandbox as collection and request scripts. Use it to inspect or reshape requests before they hit reverse proxy / static files, and to assert on responses afterward.
The tab has two sections: PreRequest and PostRequest. Unlike request editor scripts, there is no Before / Main / After stage axis — each section is a flat ordered list. Every row’s header is a matching path pattern (default index.html), not a display name. Only enabled rows whose pattern matches the request pathname run for that request.
| Match pattern | Matches |
|---|---|
* | Every request path |
Pattern with / | Full pathname (leading / optional), for example /index.html or /api/* |
Pattern without / | Basename only, for example *.png or index.html (matches /index.html and /docs/index.html) |
Narrow matchPath when you can — pre scripts add latency to every matching request, and the shared script runner serializes work across servers.
| Phase | When it runs | What you can do |
|---|---|---|
| PreRequest | After access logging starts, before CORS, custom headers, reverse proxy, aliases, static files, and routing. Fully awaited before the next middleware runs | Read and mutate hc.request (url/path, headers). Call await hc.send(...) / await hc.sendJSON(...) to short-circuit with that status, headers, and body (see Scripting — hc.send). Call hc.execution.skipRequest() alone to end with 204. Request body is not available in v1 (the stream is not consumed) |
| PostRequest | After the response finishes streaming to the client (including proxied upstream and static files) | Read hc.response (status, headers, body, timing). Scripts cannot change what was already sent — hc.send / hc.sendJSON are ignored with a warning. Bodies larger than about 5 MB are truncated for capture |
When a Run command companion process is configured, requests typically reach it through a reverse-proxy rule. Pre-request scripts still run first and must finish before the proxy forwards the request, so the companion never sees traffic until mutations (and optional hc.send / skipRequest) are applied.
Save hot-applies script list changes on a running server — you do not need Stop + Start for script edits alone. Other runtime fields (root, port, proxy, SSL, and so on) still require a restart.
| Control / menu | Purpose |
|---|---|
| Add, Snippets, Import, Export, Paste, Help | Toolbar above the sections (Add / Paste target PreRequest by default) |
| Section ⋯ → New script | Adds an empty inline script to that section with match path index.html |
| Section ⋯ → Snippets | Create or insert a snippet reference into that section |
| Row checkbox | Enable or disable the script |
| Match path input | Glob that decides whether the script runs for the current request |
Scripts use the same hc API as elsewhere — see Scripting. On live-server runs, hc.info.liveserverId is the saved live server database id as a string (empty outside a live-server script run). Console lines, hc.test results, and script errors appear in the Logs panel interleaved with access lines, for example [12:34:56.789] pre /index.html ✓ status is 200.
PreRequest example (matchPath: *):
hc.request.headers.push({ key: "X-Debug", value: "1", enabled: true });PostRequest example (matchPath: index.html):
hc.test("index is 200", () => {
hc.expect(hc.response.code).to.equal(200);
});Save and start
| Control | Behavior |
|---|---|
| Save | Persists the saved config only. Does not restart a running instance |
| Start Server | Saves if needed, starts the server, opens a browser tab at the resolved open URL (openPath or remembered last path), and closes the panel |
| Stop Server | Shown when this saved server is running — stops that instance without deleting the saved config |
A fixed port fails to start if another process already uses it. Blank port auto-selects from 5500 upward on the configured bind host.
Aliases
On the General tab, choose Add alias to map a URL path to a filesystem target.
| Field | Rules |
|---|---|
| Path | Must start with / (for example /assets) |
| Target | Absolute path, or a path relative to the server root (for example build/assets) |
Aliases are mounted before the document root, so they take precedence over files under the root for the same path prefix. Directory index filenames from Index files apply to alias mounts the same way as the document root.
Logs
Open logs from a Server Logs row, a Live Servers row menu → Logs, or the footer when a session is selected. The panel title is Logs: <name> with the origin, Logging, or Stopped in the subtitle.
While that start is running, HarborClient streams Express access lines (method, URL, status, duration, content length) for HTTP and HTTPS. Script console output, hc.test results, script errors, and companion process output stream into the same panel interleaved with access lines. Each start keeps an in-memory ring buffer of up to 1000 lines.
Stopping a server keeps the session and its lines under Server Logs until you clear them. Starting again adds a new Server Logs row with a fresh buffer; earlier starts remain available until erased.
| Control | Purpose |
|---|---|
| Clear | Clears the panel and the buffer for the open session only (does not remove the sidebar row) |
| Add logs to chat | When AI is available, opens chat with an @logs.<uuid> reference for the whole buffer |
You can also select lines in the log view and copy a ranged @logs.<uuid>#start.end reference to chat when AI is available. Use the Server Logs section erase control to clear retained sessions from the sidebar (see Server Logs).
Saved configs vs running instances
A saved live server is a registry entry (name, root, port, open path, remember-last / last opened path, index files, host, aliases, watch, response headers, routing rules, SSL, CORS including exposed headers and max age, preRequestScripts, and postRequestScripts). A running instance is the process listening on a port.
- Save updates the registry. Most runtime fields keep the old config on a running instance until you Stop and Start again. Script list edits (
preRequestScripts/postRequestScripts) hot-apply on Save without a restart. - Delete removes the saved entry and warns that running instances are not stopped — stop them first if you want the port freed.
- Starting from the sidebar or Start Server binds the new instance to the saved id and opens a Live Page at the resolved open URL.
AI assistant
When the AI assistant is available:
- Sidebar Copy to chat inserts
@live-server.<uuid>so the assistant can inspect that server. - Logs Add logs to chat (or a selected line range) inserts
@logs.<uuid>or@logs.<uuid>#start.end. - The assistant can list, get, start, stop, create, update, delete live servers, and read or clear logs — mutating tools run only when you explicitly ask.
Prefer asking by display name in chat; the @ tokens carry the uuid for tools.
Plugins
Plugins with the live-server permission can manage saved and running servers through hc.liveServers (list, get, create, update, delete, start, stop, logs, and change events). Plugin start does not open a browser tab — use hc.livePage with the browser permission when you need a Live Page. See SDK — Themes and storage (hc.liveServers) and SDK — Permissions.
See also
- Live pages — embedded browser sessions that can load a live server origin
- Scripting —
hcAPI used by live-server PreRequest / PostRequest scripts - AI assistant — chat pointers and tools for live servers and logs
- Features — product overview
- Plugin SDK — Themes and storage —
hc.liveServersAPI - Plugin SDK — Permissions —
live-serverpermission