# zidane-ui/server

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

Import: `import { … } from 'zidane-ui/server'`. Source: [ui/src/server/index.ts](https://github.com/Tahul/zidane/blob/main/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`](https://zidane.si/docs/reference/ui-server-testing.md). Browser builds fail to resolve this entry. See [Connecting a host](https://zidane.si/docs/ui-adapters.md#your-server-over-http-and-sse).

```ts
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

### `createLocalEnvironment`

Function.

Creates an [`EnvironmentFactory`](https://zidane.si/docs/reference/ui-server.md#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.

```ts
function createLocalEnvironment(options: LocalEnvironmentOptions): EnvironmentFactory
```

**Parameters**

- `options` (`LocalEnvironmentOptions`): The provider and optional model, tools, system prompt, store, data directory, and settings.

**Returns** `EnvironmentFactory`

Source: [ui/src/server/environment.ts:55](https://github.com/Tahul/zidane/blob/main/ui/src/server/environment.ts#L55)

### `createSseHandler`

Function.

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.

```ts
function createSseHandler(options: SseHandlerOptions): SseHandler
```

**Parameters**

- `options` (`SseHandlerOptions`): The environment, working directory, and `authorize` check, plus optional base path, models, and stream tuning.

**Returns** `SseHandler`

Source: [ui/src/server/sse-handler.ts:100](https://github.com/Tahul/zidane/blob/main/ui/src/server/sse-handler.ts#L100)

## Constants

### `LOCAL_PROVIDER_KEY`

Constant.

The provider key sessions run under in a local environment.

```ts
const LOCAL_PROVIDER_KEY = 'local'
```

Source: [ui/src/server/environment.ts:48](https://github.com/Tahul/zidane/blob/main/ui/src/server/environment.ts#L48)

## Interfaces

### `EnvironmentFactory`

Interface.

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

```ts
interface EnvironmentFactory
```

**Properties**

- `dispose?` (`() => void`): Releases what the factory made for its environments. `createSseHandler` calls it from `close()`.

Source: [ui/src/server/environment.ts:41](https://github.com/Tahul/zidane/blob/main/ui/src/server/environment.ts#L41)

### `LocalEnvironmentOptions`

Interface.

Options for [`createLocalEnvironment`](https://zidane.si/docs/reference/ui-server.md#createLocalEnvironment).

```ts
interface LocalEnvironmentOptions
```

**Properties**

- `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`).
- `provider` (`Provider`): 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.

Source: [ui/src/server/environment.ts:23](https://github.com/Tahul/zidane/blob/main/ui/src/server/environment.ts#L23)

### `SseHandler`

Interface.

A request handler from [`createSseHandler`](https://zidane.si/docs/reference/ui-server.md#createSseHandler): a Web-standard function from `Request` to `Response` that also exposes the engine and a `close` method.

```ts
interface SseHandler
```

**Properties**

- `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.

Source: [ui/src/server/sse-handler.ts:66](https://github.com/Tahul/zidane/blob/main/ui/src/server/sse-handler.ts#L66)

### `SseHandlerOptions`

Interface.

Options for [`createSseHandler`](https://zidane.si/docs/reference/ui-server.md#createSseHandler).

```ts
interface SseHandlerOptions
```

**Properties**

- `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'`.
- `cwd` (`string`): Working directory of every new session: the agent's tools act here.
- `environment` (`EnvironmentFactory`): 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).

Source: [ui/src/server/sse-handler.ts:43](https://github.com/Tahul/zidane/blob/main/ui/src/server/sse-handler.ts#L43)