Cloud Mode

Cloud mode turns on three things that are off in self-hosted:

Clerk authentication — login required, JWTs attached to every API request.
Cloud sync — resumes round-trip through a NestJS Core API, with version history and resume sharing.
agent-service (TypeScript, backend-side) — chat, interview, translation, JD-optimize, PDF parse.

How mode detection works

apps/web/src/lib/config/app.ts resolves the mode:

// pseudo-code
const explicit = process.env.NEXT_PUBLIC_APP_MODE
const hasClerk = !!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

export const APP_MODE =
  explicit ?? (hasClerk ? 'cloud' : 'self-hosted')

src/middleware.ts switches at module load between Clerk’s clerkMiddleware and a no-op handler based on this. There is no runtime toggle — the mode is baked at build time.

If you set NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY but forget NEXT_PUBLIC_API_URL, the app will still boot in cloud mode and every authenticated request will 404. Set both, or neither.

Environment variables

Variable	Required (cloud)	Purpose
`NEXT_PUBLIC_APP_MODE`	optional	`cloud`. Defaults to `cloud` if a Clerk key is present.
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	yes	Public Clerk key. Also triggers cloud-mode auto-detection.
`CLERK_SECRET_KEY`	yes	Server-side Clerk key.
`NEXT_PUBLIC_API_URL`	yes	The gateway origin — one URL for the whole backend (dev default `http://localhost:3110`). The gateway routes `/api/*` to the Core API / agent by path prefix.

Backend services

The backend (Core API + agent) is deployed separately from this monorepo, fronted by a single gateway. For local cloud-mode development, run the backend and point NEXT_PUBLIC_API_URL at its gateway (dev default http://localhost:3110) — the frontend only ever needs that one URL. If you only want to develop the frontend, self-hosted mode is faster.

Auth flow

Clerk issues a JWT on sign-in.
apps/web/src/lib/api/httpClient.ts attaches that JWT as a Bearer token via an Axios request interceptor (configureHttpClient).
Both httpClient.api and httpClient.agent point at the same gateway origin and share the same interceptor — you should not pass tokens manually.

See Architecture → HTTP clients for the full request path.

Introduction

Self-hosting & deployment

Architecture

MCP server

Development

How mode detection works

Environment variables

Backend services

Auth flow

​How mode detection works

​Environment variables

​Backend services

​Auth flow

How mode detection works

Environment variables

Backend services

Auth flow