feat(template-agent-builder): make WorkOS auth and EE license optional in dev (#18171)

## Summary

The Agent Builder template could not start unless WorkOS auth
credentials and a `MASTRA_EE_LICENSE` were both set, which made it hard
to try the template locally. This change makes both optional for local
development so the template boots out of the box.

- **Auth is now optional.** WorkOS AuthKit + RBAC follow the same
env-gated pattern already used for the Composio, Slack, and Browserbase
integrations: they are only enabled when the WorkOS variables are
present. With them unset, the template runs without authentication.
- **The redundant startup license check is removed.** The license is
still enforced by `@mastra/editor` for production use (with a
development bypass), so the template's own fail-fast guard was redundant
and blocked local dev. Development no longer requires a license.

## Changes

- `src/mastra/auth.ts`: `initWorkOS` returns `null` when the WorkOS env
vars are not all set, instead of throwing.
- `src/mastra/index.ts`: `auth`/`rbac` are spread into the server config
only when WorkOS is configured; removed the `requireEnterpriseLicense()`
startup call.
- `src/mastra/env.ts`: removed the now-unused `requireEnterpriseLicense`
and `requiredEnv` helpers.
- `.env.example`: WorkOS moved to an optional section; license
documented as required for production only.
- `README.md`: WorkOS listed under optional integrations; license framed
as production-only with a dev note.

## Test plan

- Copy the template out of the monorepo, `pnpm install`, set only
`OPENAI_API_KEY`, run `mastra dev` — it boots with no auth and no
license.
- Add `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, `WORKOS_COOKIE_PASSWORD` and
restart — auth + RBAC are enabled.

## Note

This PR is based on the playground request-context fix branch so its
diff is scoped to the template only. Rebase onto `main` once that PR
merges.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## ELI5 (Explain Like I'm 5)

This PR makes it possible to run the Agent Builder template on your
computer without needing to set up special authentication or buy an
enterprise license first. Instead of requiring all the setup details
before you can even start the app, it now checks if you have them and
skips authentication if you don't, letting you test and develop locally
with just the OpenAI API key.

## Changes Summary

### Core Functionality Changes

**Authentication made optional for local development:**
- `src/mastra/auth.ts`: The `initWorkOS` function now returns `null`
when WorkOS environment variables (`WORKOS_API_KEY`, `WORKOS_CLIENT_ID`,
`WORKOS_COOKIE_PASSWORD`) are missing, instead of throwing an error.
When variables are present, it initializes WorkOS auth and RBAC as
before.
- `src/mastra/index.ts`: The Mastra server configuration now
conditionally includes `auth` and `rbac` only when WorkOS is properly
configured. Removed the unconditional `requireEnterpriseLicense()`
startup-time check.
- `src/mastra/env.ts`: Removed the `requiredEnv` and
`requireEnterpriseLicense` helper functions that are no longer needed
with the optional authentication pattern.

### Configuration & Documentation Updates

**Updated environment variable documentation:**
- `.env.example`: Clarified that `OPENAI_API_KEY` powers builder-created
agents and that `MASTRA_EE_LICENSE` is required only for production
(development runs without it). Expanded WorkOS section to explain that
AuthKit + RBAC are only enabled when all required WorkOS variables are
set.
- `README.md`: Updated to reflect that WorkOS AuthKit
authentication/RBAC is optional, adjusted license prerequisites for
production vs. development, and documented that the template runs
without authentication when WorkOS values are unset.

### Model & Dependency Updates

**Model configuration:**
- `src/mastra/index.ts`: Updated the builder model allowlist to use the
`gpt-5.4-*` family with `gpt-5.4-nano` as the default model. Removed
redundant builder features configuration block.

**New dependencies:**
- `package.json`: Added `@mastra/stagehand: "latest"` and `zod:
"^4.3.6"` as direct dependencies (zod was previously relied upon as a
peer of `@mastra/core`).

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: YJ <yj@example.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>

Author: 3 people

templates/template-agent-builder/.env.example

@@ -1,9 +1,13 @@
 # Required
-# Agent Builder is an Enterprise feature. Use a valid license key (at least 32 characters).
-MASTRA_EE_LICENSE=
+# OPENAI_API_KEY powers builder-created agents that use the default OpenAI model.
 OPENAI_API_KEY=
 
-# Required: WorkOS AuthKit + RBAC
+# Required for production: Agent Builder is an Enterprise feature.
+# Use a valid license key (at least 32 characters). Development runs without one.
+MASTRA_EE_LICENSE=
+
+# Optional: WorkOS AuthKit + RBAC
+# Enables authentication and RBAC only when all three values are set.
 # WORKOS_COOKIE_PASSWORD must be at least 32 characters.
 WORKOS_API_KEY=
 WORKOS_CLIENT_ID=

templates/template-agent-builder/README.md

@@ -5,7 +5,7 @@ A minimal [Mastra](https://mastra.ai) Agent Builder template with safe defaults.
 ## Features
 
 - Agent Builder enabled by default
-- WorkOS AuthKit authentication and WorkOS-backed RBAC permissions
+- Optional WorkOS AuthKit authentication and WorkOS-backed RBAC permissions
 - Local filesystem workspace at `.mastra/workspace`
 - No starter agents, tools, or workflows
 - Observational memory enabled for builder-created agents
@@ -15,8 +15,7 @@ A minimal [Mastra](https://mastra.ai) Agent Builder template with safe defaults.
 
 - Node.js 22.13 or newer
 - An OpenAI API key
-- A valid `MASTRA_EE_LICENSE` for Agent Builder
-- WorkOS AuthKit credentials for authentication/RBAC
+- A valid `MASTRA_EE_LICENSE` for running Agent Builder in production
 
 ## Quickstart
 
@@ -28,10 +27,10 @@ A minimal [Mastra](https://mastra.ai) Agent Builder template with safe defaults.
 
 2. **Configure environment variables**
    Copy `.env.example` to `.env`, then set:
-   - `MASTRA_EE_LICENSE` — required; the template fails fast if it is missing or shorter than 32 characters.
+   - `MASTRA_EE_LICENSE` — required to run Agent Builder in production. Development environments run without one.
    - `OPENAI_API_KEY` — required for builder-created agents that use the default OpenAI model.
-   - `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, and `WORKOS_COOKIE_PASSWORD` — required for AuthKit login and RBAC. The cookie password must be at least 32 characters.
-   - `WORKOS_REDIRECT_URI` — defaults to `http://localhost:4111/api/auth/callback`.
+
+   Authentication is optional. See [Optional integrations](#optional-integrations) for WorkOS and other providers.
 
 3. **Start Mastra**
 
@@ -46,6 +45,7 @@ A minimal [Mastra](https://mastra.ai) Agent Builder template with safe defaults.
 
 The template does not register optional integrations with empty credentials. They appear only after you set their required environment variables:
 
+- **WorkOS AuthKit (auth + RBAC)**: set `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, and `WORKOS_COOKIE_PASSWORD` (the cookie password must be at least 32 characters). `WORKOS_REDIRECT_URI` is optional and defaults to `http://localhost:4111/api/auth/callback`. When these are unset, the template runs without authentication.
 - **Composio**: set `COMPOSIO_API_KEY`.
 - **Slack**: set `SLACK_APP_CONFIG_TOKEN` and `SLACK_APP_CONFIG_REFRESH_TOKEN`. `SLACK_BASE_URL` is optional.
 - **Browserbase + Stagehand**: set both `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`.

templates/template-agent-builder/package.json

@@ -16,7 +16,8 @@
     "@mastra/libsql": "latest",
     "@mastra/observability": "latest",
     "@mastra/slack": "latest",
-    "@mastra/stagehand": "latest"
+    "@mastra/stagehand": "latest",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "latest",

templates/template-agent-builder/src/mastra/auth.ts

@@ -1,11 +1,11 @@
 import { MastraAuthWorkos, MastraRBACWorkos } from '@mastra/auth-workos';
 
-import { requiredEnv } from './env';
+import { hasEnv } from './env';
 
 export async function initWorkOS() {
-  requiredEnv('WORKOS_API_KEY');
-  requiredEnv('WORKOS_CLIENT_ID');
-  requiredEnv('WORKOS_COOKIE_PASSWORD');
+  if (!hasEnv('WORKOS_API_KEY') || !hasEnv('WORKOS_CLIENT_ID') || !hasEnv('WORKOS_COOKIE_PASSWORD')) {
+    return null;
+  }
 
   const mastraAuth = new MastraAuthWorkos({
     redirectUri: process.env.WORKOS_REDIRECT_URI || 'http://localhost:4111/api/auth/callback',

templates/template-agent-builder/src/mastra/env.ts

@@ -1,25 +1,3 @@
 export const getEnv = (name: string) => process.env[name]?.trim();
 
 export const hasEnv = (name: string) => Boolean(getEnv(name));
-
-export const requiredEnv = (name: string) => {
-  const value = getEnv(name);
-
-  if (!value) {
-    throw new Error(`Missing required environment variable: ${name}. Add it to .env before starting.`);
-  }
-
-  return value;
-};
-
-export const requireEnterpriseLicense = () => {
-  const license = requiredEnv('MASTRA_EE_LICENSE');
-
-  if (license.length < 32) {
-    throw new Error(
-      'Agent Builder requires a valid MASTRA_EE_LICENSE with at least 32 characters. Add it to .env before starting.',
-    );
-  }
-
-  return license;
-};

templates/template-agent-builder/src/mastra/index.ts

@@ -8,10 +8,9 @@ import { SlackProvider } from '@mastra/slack';
 import { StagehandBrowser } from '@mastra/stagehand';
 
 import { initWorkOS } from './auth';
-import { getEnv, hasEnv, requireEnterpriseLicense } from './env';
+import { getEnv, hasEnv } from './env';
 import { workspace } from './workspace';
 
-requireEnterpriseLicense();
 const workos = await initWorkOS();
 
 const storage = new LibSQLStore({
@@ -50,18 +49,6 @@ const editor = new MastraEditor({
     : {}),
   builder: {
     enabled: true,
-    features: {
-      agent: {
-        tools: true,
-        agents: true,
-        workflows: true,
-        favorites: true,
-        skills: true,
-        model: true,
-        browser: hasBrowserbase,
-        avatarUpload: true,
-      },
-    },
     configuration: {
       agent: {
         workspace: { type: 'id', workspaceId: workspace.id },
@@ -72,10 +59,15 @@ const editor = new MastraEditor({
           },
         },
         models: {
-          allowed: [{ provider: 'openai' }, { provider: 'anthropic', modelId: 'claude-sonnet-4-6' }],
+          allowed: [
+            { provider: 'openai', modelId: 'gpt-5.4-nano' },
+            { provider: 'openai', modelId: 'gpt-5.4-mini' },
+            { provider: 'openai', modelId: 'gpt-5.4' },
+            { provider: 'openai', modelId: 'gpt-5.4-pro' },
+          ],
           default: {
             provider: 'openai',
-            modelId: 'gpt-5',
+            modelId: 'gpt-5.4-nano',
           },
         },
         ...(hasBrowserbase
@@ -103,8 +95,12 @@ export const mastra = new Mastra({
     sourcemap: true,
   },
   server: {
-    auth: workos.mastraAuth,
-    rbac: workos.rbacProvider,
+    ...(workos
+      ? {
+          auth: workos.mastraAuth,
+          rbac: workos.rbacProvider,
+        }
+      : {}),
     build: {
       swaggerUI: true,
     },