Skip to content
zidane
UI kit reference

zidane-ui/server

Server helpers that serve a zidane chat engine to the browser over HTTP and SSE.

import { … } from 'zidane-ui/server'ui/src/server/index.ts

Use this entry point on Node or Bun to serve createSseHost. createSseHandler returns a standard (request: Request) => Promise<Response> that runs the chat engine. createLocalEnvironment builds the agent behind it. The offline createScriptedProvider and demoTools are in zidane-ui/server/testing. Browser builds fail to resolve this entry. See Connecting a host.

TypeScript
import { createLocalEnvironment, createSseHandler } from 'zidane-ui/server'
import { createScriptedProvider, demoTools } from 'zidane-ui/server/testing'

const handler = createSseHandler({
  environment: createLocalEnvironment({ provider: createScriptedProvider(), tools: demoTools }),
  cwd: process.cwd(),
  basePath: '/api/chat',
  authorize: () => true,
})

Bun.serve({ port: 4380, idleTimeout: 0, fetch: handler })

Functions#

createLocalEnvironmentFunction#

Creates an EnvironmentFactory for a self-contained environment: one provider, a fixed tool set, sessions in a store you pass, and no user config, MCP servers, or extensions. Call its dispose() when done: without a dataDir option it removes the temp directory the environment made.

TypeScript
function createLocalEnvironment(options: LocalEnvironmentOptions): EnvironmentFactory

Parameters

Parameters
NameTypeDescription
optionsLocalEnvironmentOptions

The provider and optional model, tools, system prompt, store, data directory, and settings.

ui/src/server/environment.ts:55

createSseHandlerFunction#

Creates a Web-standard request handler that runs zidane's chat engine and serves it over HTTP and server-sent events, for createSseHost to talk to. Every request goes through authorize first, and the agent's tools run on this machine.

TypeScript
function createSseHandler(options: SseHandlerOptions): SseHandler

Parameters

Parameters
NameTypeDescription
optionsSseHandlerOptions

The environment, working directory, and authorize check, plus optional base path, models, and stream tuning.

Returns

SseHandler

ui/src/server/sse-handler.ts:100

Constants#

LOCAL_PROVIDER_KEYConstant#

The provider key sessions run under in a local environment.

TypeScript
const LOCAL_PROVIDER_KEY = 'local'

ui/src/server/environment.ts:48

Interfaces#

EnvironmentFactoryInterface#

Builds a chat engine environment. Receives the broadcast function the engine uses to publish signals to clients.

TypeScript
interface EnvironmentFactory

Properties

EnvironmentFactory properties
NameTypeDescription
dispose?() => void

Releases what the factory made for its environments. createSseHandler calls it from close().

ui/src/server/environment.ts:41

LocalEnvironmentOptionsInterface#

Options for createLocalEnvironment.

TypeScript
interface LocalEnvironmentOptions

Properties

LocalEnvironmentOptions properties
NameTypeDescription
dataDir?string

Scratch directory for the engine's own files. Default: a temp dir made on first use and removed by dispose().

model?string

Model id passed to the provider (default: the provider's meta.defaultModel).

providerProvider

The provider every session runs on.

settings?Partial<HostSettings>

Settings overrides; tool approvals (approvalMode) are off by default.

store?SessionStore

Where sessions persist. Default: in memory, lost on restart.

system?string

System prompt. Default: zidane's built-in one.

tools?Record<string, ToolDef>

The agent's tools. Default none: the agent can only talk.

ui/src/server/environment.ts:23

SseHandlerInterface#

A request handler from createSseHandler: a Web-standard function from Request to Response that also exposes the engine and a close method.

TypeScript
interface SseHandler

Properties

SseHandler properties
NameTypeDescription
close() => Promise<void>

Stop the engine, end every stream, and remove the environment's temp directory.

engine() => Promise<ChatHost>

The engine. Starts it when no request has started it yet.

ui/src/server/sse-handler.ts:66

SseHandlerOptionsInterface#

Options for createSseHandler.

TypeScript
interface SseHandlerOptions

Properties

SseHandlerOptions properties
NameTypeDescription
authorize(request: Request) => boolean | Promise<boolean>

Called on every request before anything else; resolve false to answer 401. Required: pass () => true only for a server nobody else can reach.

basePath?string

Path the handler is mounted at (default ''), e.g. '/api/chat'.

cwdstring

Working directory of every new session: the agent's tools act here.

environmentEnvironmentFactory

zidane's chat environment: createLocalEnvironment({ provider, tools }), or createDaemonEnvironment from zidane/ipc for the machine's own config.

heartbeatMs?number

Keep-alive comment interval in ms (default 15000).

models?readonly ChatModelProvider[]

What GET /models lists (default none: the composer hides its model picker).

newSession?Omit<CreateSessionRequest, 'title' | 'cwd'>

Extra fields for every new session (providerKey, modelId, agentId).

replayLimit?number

Stream records kept per session for Last-Event-ID resumes (default 2000).

ui/src/server/sse-handler.ts:43