Live servers

Create, start, stop, and inspect Harbor Live Servers (loopback static file servers with optional CORS, path aliases, and file watching).

Requires the live-server permission. This is separate from hc.server (plugin echo server under the server permission).

Saved-config update / delete do not restart or stop a running instance. start returns the running instance and does not open a browser tab — call hc.livePage(origin) when you also have the browser permission.

export async function activate(hc: PluginContext): Promise<void> {
  const saved = await hc.liveServers.create({
    name: 'Docs preview',
    root: '/absolute/path/to/site',
    port: null,
    watch: true
  });

  const running = await hc.liveServers.start({ savedId: saved.id });
  console.log(running.origin, running.port);

  const status = await hc.liveServers.getStatus({ savedId: saved.id });
  const logs = await hc.liveServers.getLogs({ savedId: saved.id, limit: 50 });

  hc.liveServers.onRunningChanged((list) => {
    console.log('running count', list.length);
  });
  hc.liveServers.onRequestLog((entry) => {
    console.log(entry.method, entry.url, entry.statusCode);
  });
}

hc.liveServers.clearLogs(query)

Available since v2.9.0

Signature:(query: LiveServerLogsQuery) => Promise<void>

Clears the in-memory request log buffer for a running instance.

hc.liveServers.create(input)

Available since v2.0.0

Signature:(input: CreateLiveServerInput) => Promise<LiveServer>

Persists a new saved server and returns the created row.

hc.liveServers.delete(id)

Available since v2.0.0

Signature:(id: number) => Promise<void>

Deletes a saved server. Does not stop a running instance started from that saved id.

hc.liveServers.get(idOrUuid)

Available since v2.0.0

Signature:(idOrUuid: number | string) => Promise<LiveServer | null>

Returns one saved server by database id or uuid, or null when not found.

hc.liveServers.getLogs(query)

Available since v2.9.0

Signature:(query: LiveServerLogsQuery & { limit?: number }) => Promise<LiveServerRequestLogEntry[]>

Returns trailing buffered Express access-log lines (default limit 100, max 1000). Empty when the instance is not running.

hc.liveServers.getStatus(query)

Available since v2.9.0

Signature:(query: { id: string } | { savedId: number }) => Promise<RunningLiveServer | null>

Returns the running instance for the query, or null when not running.

hc.liveServers.list()

Available since v2.0.0

Signature:() => Promise<LiveServer[]>

Lists saved live servers from the local registry.

hc.liveServers.listRunning()

Available since v2.9.0

Signature:() => Promise<RunningLiveServer[]>

Lists currently running instances.

hc.liveServers.onRequestLog(listener)

Available since v2.9.0

Signature:(listener: (entry: LiveServerRequestLogEntry) => void) => Disposable

Subscribes to Express access-log lines from running live servers.

hc.liveServers.onRunningChanged(listener)

Available since v2.9.0

Signature:(listener: (running: RunningLiveServer[]) => void) => Disposable

Subscribes to start/stop list changes (including changes from the Harbor UI).

hc.liveServers.start(input)

Available since v2.7.0

Signature:(input: StartLiveServerInput) => Promise<RunningLiveServer>

Starts from savedId (loads config from the registry when config is omitted) and/or an ad-hoc config. Returns the running instance with assigned port and http://127.0.0.1:<port> origin.

hc.liveServers.stop(query)

Available since v2.7.0

Signature:(query: { id: string } | { savedId: number }) => Promise<void>

Stops one running instance by runtime id or saved id.

hc.liveServers.update(input)

Available since v2.0.0

Signature:(input: UpdateLiveServerInput) => Promise<LiveServer>

Updates a saved server. Does not restart a running instance.