Server mode

In server mode the docs app is a running Next server instead of a folder of files. A proxy.ts file sees every request first, so it can sign readers in, gate pages and answer Ask AI. Use it when you need those features and don't serve the docs from your Nest app.

When to use server modeCopy Anchor Link

If your Nest app already serves the docs, you don't need server mode. mountOrbitDocs enforces access and serves Ask AI from the static build.

Turn it onCopy Anchor Link

export default defineConfig({
  // …
  output: { mode: 'server', basePath: '' },
});

import { orbitProxy } from '@orbitdocs/next/proxy';

export default orbitProxy();

export const config = {
  matcher: ['/((?!_next/static|_next/image).*)'],
};

npx orbitdocs build

ORBITDOCS_AUTH_SECRET=$(openssl rand -hex 32) npx next start -p 3001

What proxy.ts doesCopy Anchor Link

orbitProxy() reads two files that orbitdocs build writes: .orbitdocs/access.json (from access) and .orbitdocs/ai.json (from ai). For each request it:

1. Returns 404 for orbitdocs-access.json and orbitdocs-ai.json, so the manifests are never served.
2. Answers Ask AI (/_ai/*) and MCP (/mcp, /mcp/<api id>) when the config has ai.
3. Answers sign-in routes (/_auth/*) when the config has access.
4. Gates the page. Readers without access are sent to the login page.
5. Lets the request through to Next.

Without access and ai, it lets every request through. A site with neither section can keep the file.

OptionsCopy Anchor Link

export default orbitProxy({ publicUrl: 'https://docs.acme.com' });

Environment variablesCopy Anchor Link

Secrets are read from the server's environment at request time, never from the build:

The full list with defaults is on Environment variables.

Run it in a containerCopy Anchor Link

The CLI's docker target only covers static builds. For server mode, build first and copy the docs app into a Node image:

FROM node:22-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
ENV NODE_ENV=production
EXPOSE 3000
CMD ["npx", "next", "start", "-p", "3000"]

node_modules
out

The image installs its own node_modules so native packages match Linux. .next/, openapi/ and .orbitdocs/ come from your build.

cd docs
npx orbitdocs build          # writes .next/, openapi/ and .orbitdocs/
docker build -t acme-docs .
docker run -p 3000:3000 -e ORBITDOCS_AUTH_SECRET=… acme-docs

Build on the host or in CI, not inside the image: extraction needs your Nest app, which is outside the docs folder.

Differences from a static buildCopy Anchor Link

• Redirects are real 301/302 responses, wildcards included.
• URLs keep their trailing slash (/quickstart/), the same as static.
• orbitdocs deploy accepts only --target vercel in this mode.
• orbitdocs publish refuses server builds. The platform hosts static builds and adds its own server.

Next stepsCopy Anchor Link