Server API

Overview

The server in packages/nikcli/src/server/server.ts is the shared HTTP surface for web clients, the desktop app, the TUI control channel, mobile pairing, PTYs, workspace routing, connector settings, MCP, analytics, and the generated SDK.

It runs on Bun.serve with a hand-written request pipeline in server/server-router.ts. Every declared route lives in a typed effect/unstable/httpapi group under packages/nikcli/src/server/httpapi/, assembled into one API in httpapi/public.ts and served through HttpApiBridge.

Start a server

Use nikcli serve for the general API server, nikcli web for the web app workflow, or nikcli mobile serve for the mobile-first host. The TUI also starts an internal worker server when network options are provided.

nikcli serve --hostname 127.0.0.1 --port 4096

NIKCLI_SERVER_PASSWORD=secret \
  nikcli serve --hostname 0.0.0.0 --port 4096

NIKCLI_SERVER_PASSWORD=secret \
  nikcli mobile serve --hostname 0.0.0.0 --port 4096 --pair

Request pipeline

ServerRouter.make() builds the fetch handler. Each request walks the same path:

1. Body limit. Oversized bodies are rejected before anything is parsed (middleware/body-limit.ts).
2. CORS preflight. OPTIONS short-circuits with the computed CORS headers.
3. Public share routes. /s/:shareID, /share/:shareID, and /api/share/:shareID answer before any auth check.
4. Auth. Auth.authenticate() resolves a principal from mobile tokens, account tokens, Tailscale identity, or Basic Auth. Public paths are allowed through unauthenticated.
5. Global vs instance split. isInstanceLessPath() routes /global, /user, /account (plus the /sync/stream SSE feed) to the global branch, which never binds a project directory.
6. Context resolution. Everything else resolves a directory and workspace, proxies remote workspaces through ServerProxy, and enters WorkspaceContext.provide + withInstanceAsync.
7. Websocket upgrades. PTY connect paths upgrade in place instead of returning a body.
8. Raw handlers. PublicRoutes.instanceRequest() claims SSE, prompt streaming, chatbot webhooks, and the extra.ts routes.
9. HttpApi bridge. If HttpApiBridge.supports(path, method) matches, the typed handler answers.
10. Fallback. Unmatched non-/mobile paths are proxied to app.nikcli-ai.dev so the hosted web app can be served from the same origin.

Auth layers

Server auth is layered so browser user sessions, mobile device tokens, Tailscale identity, and Basic Auth can coexist. All of it resolves in server/httpapi/auth.ts, which returns a single principal the rest of the pipeline reads via ServerRouter.principal().

NIKCLI_SERVER_USERNAME=nikcli \
NIKCLI_SERVER_PASSWORD=secret \
  nikcli serve --hostname 0.0.0.0 --port 4096

NIKCLI_SERVER_TAILSCALE_AUTH=1 \
NIKCLI_SERVER_TAILSCALE_USERS=alice@example.com,bob@example.com \
  nikcli serve --hostname 127.0.0.1 --port 4096

Instance & workspace context

After auth, instance-bound routes run inside a project instance. The server chooses the directory from the directory query parameter, the x-nikcli-directory header, the current process cwd, or the directory stored on a session referenced by the route path.

Workspace routing then looks at workspace, x-nikcli-workspace, or the route session's workspaceID. Local workspaces replace the directory with the workspace target directory. Remote workspaces are proxied through ServerProxy for both HTTP and websocket upgrades.

Route groups

Every group is declared in its own file under server/httpapi/ and composed into PublicHttpApi.Api in httpapi/public.ts.

Raw handlers

A handful of paths are served as plain Request → Response functions because their shape cannot round-trip through a schema. Their contracts still live in the API — as ContractExtraHttpApi groups on PublicApi — so the generated SDK and the OpenAPI document stay complete.

Session API

httpapi/session.ts is the largest group and the core of the SDK contract. Streaming the prompt itself is the one carve-out — that lives in httpapi/prompt.ts.

Mobile API

The /mobile group is intentionally larger than the base API because it exposes a complete phone workflow. Its endpoints are declared in httpapi/mobile.ts; the implementations are split by concern across server/mobile/ and wired up in httpapi/mobile-handlers.ts.

The HttpApi bridge

httpapi/bridge.ts turns the declared API into a served one. It builds an Effect HttpRouter from PublicHttpApi.Api, keeps a machine-readable RoutePattern table for coverage checks, and exposes two entry points: handle() for instance-bound requests and handleGlobal() for the instance-less roots.

• supports(path, method) and supportsGlobal(path, method) decide whether the bridge claims a request; a miss falls through to the proxy.
• Path templates (/session/{sessionID}/message) are compiled to RegExps, with name segments matched as [^/]+.
• script/check-route-coverage.ts and test/server/routes-coverage.test.ts assert every entry in the table still matches, so a renamed path fails CI instead of 404ing in production.

Events and streaming

The server has two event styles. SSE endpoints give clients a long-lived feed; internal Bus events carry state changes between subsystems in-process.

• GET /event streams instance-scoped events; GET /global/event streams instance-less ones.
• GET /sync/stream streams the sync projection feed. See Sync.
• The /tui group publishes TuiEvent.CommandExecute so external clients can open dialogs or run commands in the active TUI.
• Permission and question routes publish request/reply events through their services.
• MCP publishes mcp.tools.changed when a connected server sends a tool-list notification.
• PTY output rides a websocket rather than SSE, upgraded in server/websocket.ts.

OpenAPI and SDK generation

Server.openapi() returns OpenApi.fromApi(PublicApi) — the document is derived from the same typed API that serves the traffic, so it cannot drift from the implementation. The API reference is rendered from that same document, endpoint by endpoint.

The JavaScript SDK is generated from that API by packages/nikcli/script/generate-httpapi-clients.ts, using @nikcli-ai/httpapi-codegen. One run emits three artifacts:

bun run --cwd packages/nikcli generate:httpapi-clients
# or, equivalently, from the SDK package:
bun run --cwd packages/sdk/js generate:httpapi

Failure modes

Source anchors