Documentation / Start building

Service setup

For a new product created with GitHub's template button, first follow getting started: run bun run init:product --name <product-slug> in the clean copy before dependency installation or product edits. The public runtime installs from npm without a package-read token. The canonical maintained checkout keeps its runtime workspace and must not run product initialization. After conversion, use the install/server contract below unchanged. This guide also supplies the setup contract for Modeinspect and fresh agent preview sandboxes.

Mode must use the user's intended Hexclave and Convex projects. A fresh clone has no service credentials: the maintainer's ignored .env.local and GitHub Actions secrets are not automatically available in Mode. Ask for missing environment variables instead of attempting to complete setup without them.

Request the environment before starting

Inspect which variable names are configured without printing their values. Ask the user to enter missing values through Mode's secure environment/secret settings, if available, or an ignored .env.local. Do not request secrets in ordinary agent chat or commit them as recorded file contents.

There are four required variables. NEXT_PUBLIC_HEXCLAVE_PROJECT_ID is the single project-ID input for Mode. The Next.js server SDK inherits that ID from the client app, and dev:mode copies it into Convex as HEXCLAVE_PROJECT_ID, together with the existing HEXCLAVE_SECRET_SERVER_KEY. Do not request a second project ID or a separate team-administration key.

Suggested request when those values are missing:

This app needs your Hexclave and Convex configuration before the preview can run. Please provide your Hexclave project ID once, its HEXCLAVE_SECRET_SERVER_KEY, your NEXT_PUBLIC_CONVEX_URL, and a development CONVEX_DEPLOY_KEY for that same Convex deployment through secure environment settings. Set the project ID as NEXT_PUBLIC_HEXCLAVE_PROJECT_ID; startup will configure the backend with that same ID automatically. Use the intended development projects. I can install dependencies now, but startup and verification must wait for those values.

Only request names that are actually missing. Blank template values do not count as configuration. Do not generate dummy values, create replacement projects, switch to anonymous/local Convex, use dev:local-auth, remove providers, or bypass authorization to avoid this request. A separate local setup is opt-in only when the user explicitly asks for it.

Installation and read-only inspection can continue while waiting. If the setup harness cannot ask for secure input, record the exact missing variable names as a user-action requirement and leave setup incomplete. Do not repeatedly retry startup or report success.

Backend sync is always required

Always request a development CONVEX_DEPLOY_KEY, even if the backend already has functions deployed. Mode must upload this checkout's functions before starting the frontend and keep syncing edits throughout the preview session. Do not skip sync, use a frontend-only command, or substitute a manual dashboard step for the deploy key.

HEXCLAVE_PROJECT_ID and HEXCLAVE_SECRET_SERVER_KEY must also exist in the Convex deployment's environment, for the same project used by Next.js. Setting them only in Mode or .env.local does not configure Convex. convex/auth.config.ts needs the project ID; the server actions need the key to recheck memberships and permissions and perform team/account operations.

bun run dev:mode loads the supplied environment, requires a deployment-specific development key (dev:...), and runs this sequence automatically:

1. bun scripts/sync-convex-env.mjs to set Convex's HEXCLAVE_PROJECT_ID and HEXCLAVE_SECRET_SERVER_KEY. It passes values through CLI stdin, never command arguments, and suppresses value-bearing CLI output. Logs report variable names only.
2. convex dev --typecheck enable --start "bun run dev --hostname 0.0.0.0" to upload functions, launch Next after the first successful push, and watch for backend edits.

Keep this single foreground command running. It owns backend sync and the frontend; do not start a second dev:backend process. Environment-setting failures stop startup. An initial function/typecheck failure prevents Next from launching until the problem is fixed and sync succeeds. Do not hide failures with || true. CI uses the same secret-safe environment sync before its backend push.

Confirm the key and NEXT_PUBLIC_CONVEX_URL refer to the same intended development deployment before startup. Do not use a production/project/preview deploy key or --prod. A cloud backend stays available when the local sync process stops, but a stopped sync process means Mode is no longer uploading edits.

Other variables are conditional, not initial blockers:

• CONVEX_DEPLOYMENT: optional deployment selector; the CLI may write it for authenticated development. A deployment-specific deploy key can select its target without this variable.
• NEXT_PUBLIC_CONVEX_SITE_URL: optional HTTP actions URL; the current frontend does not require it.
• PORT: use Mode's supplied port; defaults to 3000.
• REACTBITS_LICENSE_KEY and PIXELARTICONS_LICENSE_KEY: optional licensed asset installation, not application service configuration.
• NEXT_PUBLIC_HEXCLAVE_STRIPE_PUBLISHABLE_KEY: optional local card-update UI. Its absence does not block hosted checkout; checkout still needs real public offers configured in the intended project.
• Cloudflare account ID/API token: publishing credentials, not needed to run a Mode preview.

See .env.example for the full variable checklist and DEPLOYMENT.md for publishing and provider configuration.

Autosetup contract

Use the repository root, Node 24 (.nvmrc), and Bun (packageManager in package.json).

dev:mode checks the four required variables, reports missing names without values, validates a development deploy key, then configures backend auth and the server-action credential before starting persistent Convex sync. Next starts listening on 0.0.0.0 only after the first successful push. Passing this check proves the configuration is present, not that the credentials are valid; verify the real flows below.

Register this command with Mode's long-running process manager. Run it whenever the sandbox starts and restart it after environment changes. Never overwrite an existing .env.local with .env.example or a recorded file step. Do not rely on nohup processes surviving installation, copy another sandbox's .convex state, or hide failures with || true.

Verify in the actual preview browser

1. Open /; confirm meaningful content, no error overlay, and no missing-env or Convex WebSocket errors.
2. Sign in with a development test account through the normal UI. Verify the final URL is /app and the application shell is visible.
3. Open /app/settings while signed in. Check the team dropdown and Teams settings share the selected membership, and that a non-admin account receives only its permitted controls. Empty memberships or an empty billing-offer catalog are valid service states; card updates remain unavailable without the optional payment key.
4. Create a test note, reload, confirm it is read back from Convex, and remove it afterward.
5. Stop and restart the registered dev command to confirm the supplied configuration persists across preview sessions.

Signed-out visits to /app and /app/settings enter hosted sign-in; restricted accounts enter hosted onboarding. HTTP 200 may therefore describe an authentication page rather than the signed-in application. If interactive authentication cannot be completed, report protected-page verification as incomplete. Never weaken Convex authorization or change personal note ownership for setup.

Use the actual preview origin for Hexclave's trusted-domain/auth return configuration. If sign-in rejects it, ask for that origin to be added in the intended Hexclave project; the server key is not project-admin access. Do not assume modeinspect.com is the preview origin.

The browser must reach NEXT_PUBLIC_CONVEX_URL over HTTP/WebSocket. A sandbox's 127.0.0.1 is not automatically reachable from a remote preview browser. For an explicitly requested local setup, verify supported forwarding/proxy access; see Convex local deployment limitations.

Report failing command exit status, redacted logs, final browser URL, and the exact missing configuration or user action. A request for fresh-sandbox verification is not a successful verification result.