feat(local-mode): local-first developer experience with zero-ceremony setup

[viktormarinho]

Summary

Zero-config local-first developer experience for MCP Mesh. Run npx decocms and get a fully functional MCP gateway on your machine in seconds.

Local mode (MESH_LOCAL_MODE=true)

• First-run wizard prompts for data directory (defaults to ~/deco/)
• Auto-generates and persists BETTER_AUTH_SECRET + ENCRYPTION_KEY in secrets.json (chmod 0600)
• Seeds admin user from OS username + default org on fresh databases
• Browser auto-logs in without a login form (loopback-only, socket-level IP check)
• Home route skips org selection and redirects straight to the first org
• Local filesystem object storage (/mcp/dev-assets) in local mode
• CLI flags: --home <path>, --no-local-mode

decocms npm package

• npx decocms / npm i -g decocms && deco — user-facing CLI
• Thin wrapper in packages/studio/ that depends on @decocms/mesh
• CI workflow auto-publishes in lockstep with mesh version bumps
• Product README with features, quick start, and MCP client config

OAuth behind proxies

• /api/config exposes internalUrl only in local mode for OAuth redirect URIs
• setOAuthRedirectOrigin() in mesh-sdk lets the client use localhost:PORT for redirects
• Cross-origin postMessage support between .localhost variants (e.g. tokyo.localhost ↔ localhost:3000)
• Better Auth trusts localhost:PORT origin only when isLocalMode() is true

Security hardening

• /local-session restricted to loopback IPs via getConnInfo from hono/bun (socket-level, non-spoofable)
• server passed as Hono env in Bun.serve() for getConnInfo to work
• Seed readiness gate (markSeedComplete/waitForSeed) prevents race between seeding and auto-login
• DATABASE_URL respects user-provided value (no silent overwrite)
• Tilde expansion only handles ~ and ~/path, not ~user
• Random ENCRYPTION_KEY generated if not provided

Other

• bun run dev renamed to bun run dev:saas; new bun run dev runs scripts/dev.ts
• HTML title set to "Deco Studio"
• Fresh chat per page load with stable in-session UUID
• internalUrl removed from production /api/config responses
• Technical debt tracked in DEBT.md

Test plan

• Fresh install: npx decocms → prompted for data dir → browser opens, lands in org without login
• Restart: no prompt, same session works
• --no-local-mode: login form shown as normal
• --home ~/custom-dir: data stored there
• /local-session returns 403 from non-loopback IP
• /local-session returns 503 before seed completes, then succeeds
• OAuth popup flow works behind proxy (e.g. tokyo.localhost)
• /api/config omits internalUrl when MESH_LOCAL_MODE is not set
• bun test passes (except pre-existing Playwright/bun conflict)

🤖 Generated with Claude Code

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Should a new version be published when this PR is merged?

React with an emoji to vote on the release type:

Reaction	Type	Next Version
👍	Prerelease	2.136.2-alpha.1
🎉	Patch	2.136.2
❤️	Minor	2.137.0
🚀	Major	3.0.0

Current version: 2.136.1

Deployment

• Deploy to production (triggers ArgoCD sync after Docker image is published)

[cubic-dev-ai]

6 issues found across 15 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/api/routes/auth.ts">

<violation number="1" location="apps/mesh/src/api/routes/auth.ts:126">
P1: This unauthenticated endpoint grants full admin access with no credentials. If the server is ever bound to `0.0.0.0` (or another non-loopback address), any machine on the local network can obtain an admin session. Add a host/origin check to restrict this endpoint to loopback requests only (`127.0.0.1` / `::1` / `localhost`).</violation>
</file>

<file name="apps/mesh/scripts/dev.ts">

<violation number="1" location="apps/mesh/scripts/dev.ts:75">
P2: Tilde expansion drops the home directory for inputs like "~/dir" because `answer.slice(1)` starts with `/`. Strip the leading slash before joining so the resolved path stays under the user home.</violation>

<violation number="2" location="apps/mesh/scripts/dev.ts:119">
P2: Generate a random ENCRYPTION_KEY when none is provided instead of storing an empty string; an empty key is hashed into a deterministic value, so all installs share the same derived encryption key.</violation>
</file>

<file name="apps/mesh/src/index.ts">

<violation number="1" location="apps/mesh/src/index.ts:74">
P2: Local-mode seeding runs as a detached async task after the server starts, so `/api/auth/custom/local-session` can be called before the admin user is created and returns a 500. Gate local-session until seeding finishes or wait for the seed before exposing auto-login.</violation>
</file>

<file name="apps/mesh/src/cli.ts">

<violation number="1" location="apps/mesh/src/cli.ts:184">
P1: DATABASE_URL is unconditionally overwritten, silently ignoring user-provided values (e.g., PostgreSQL URLs). The help text documents it as a configurable env var with a default, but the code always replaces it. This breaks the PostgreSQL deployment path described in the project README.

Respect the user's DATABASE_URL when explicitly set, and only default to the SQLite path inside MESH_HOME.</violation>
</file>

<file name="apps/mesh/src/auth/local-mode.ts">

<violation number="1" location="apps/mesh/src/auth/local-mode.ts:14">
P1: Hardcoding a known admin password makes the seeded account trivially guessable. Use a generated or environment-provided secret so local-mode credentials aren’t predictable if this mode is accidentally enabled outside a dev machine.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[vibegui]

@cubic-dev-ai can you re-review?

[cubic-dev-ai]

@cubic-dev-ai can you re-review?

@vibegui I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

6 issues found across 15 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/auth/local-mode.ts">

<violation number="1" location="apps/mesh/src/auth/local-mode.ts:86">
P2: Organization slug is derived from raw OS username without normalization, so invalid slug characters can be persisted.</violation>
</file>

<file name="apps/mesh/src/cli.ts">

<violation number="1" location="apps/mesh/src/cli.ts:160">
P1: Missing non-TTY guard: if the CLI is run non-interactively (Docker, CI, systemd) without `--home` and without an existing `~/deco` directory, the `prompt()` call will hang forever. `scripts/dev.ts` correctly checks `process.stdin.isTTY` and falls back to a default, but `cli.ts` does not.</violation>
</file>

<file name="apps/mesh/scripts/dev.ts">

<violation number="1" location="apps/mesh/scripts/dev.ts:41">
P3: This file duplicates substantial startup/secrets logic from `src/cli.ts`; extract a shared module to prevent divergence and double-maintenance.</violation>

<violation number="2" location="apps/mesh/scripts/dev.ts:119">
P1: `ENCRYPTION_KEY` is initialized to an empty string, which results in a predictable global encryption key instead of a unique secret.</violation>

<violation number="3" location="apps/mesh/scripts/dev.ts:127">
P2: `secrets.json` is written without explicitly restricting file permissions, which can expose auth/encryption secrets on permissive environments.</violation>
</file>

<file name="apps/mesh/src/web/routes/login.tsx">

<violation number="1" location="apps/mesh/src/web/routes/login.tsx:75">
P2: Auto-login should retry transient local-session failures instead of failing permanently on the first 5xx response, otherwise users can get stuck on an error screen during initial startup/seeding.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/web/components/chat/task/use-task-manager.ts">

<violation number="1" location="apps/mesh/src/web/components/chat/task/use-task-manager.ts:152">
P2: This initializer resets the active task on every hook initialization/remount, causing unstable chat selection and unnecessary localStorage churn. Preserve an existing value in the initializer so only first-time initialization generates a UUID.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

2 issues found across 13 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/auth/index.ts">

<violation number="1" location="apps/mesh/src/auth/index.ts:328">
P1: The localhost trusted origin is added in all environments (and forced to `http`), which unintentionally broadens `trustedOrigins` outside development.</violation>
</file>

<file name="packages/studio/scripts/publish.sh">

<violation number="1" location="packages/studio/scripts/publish.sh:63">
P2: `package.json` restoration is not guaranteed on failure; the script can exit early and leave the file patched.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

3 issues found across 5 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/scripts/dev.ts">

<violation number="1" location="apps/mesh/scripts/dev.ts:75">
P2: Tilde expansion trims one extra character for `~<name>` inputs because `slice(2)` is used with a broad `startsWith("~")` check.</violation>
</file>

<file name="apps/mesh/src/cli.ts">

<violation number="1" location="apps/mesh/src/cli.ts:177">
P2: Interactive `~` path expansion removes one extra character (`slice(2)`), producing incorrect directories for inputs like `~mydir` and diverging from `--home` behavior.</violation>
</file>

<file name="apps/mesh/src/api/routes/auth.ts">

<violation number="1" location="apps/mesh/src/api/routes/auth.ts:132">
P0: Loopback check relies on spoofable client headers (`x-forwarded-for`, `x-real-ip`), making it trivially bypassable. Any LAN client can set `X-Forwarded-For: 127.0.0.1` to gain admin access. Additionally, the `remoteAddr === ""` fallback means any direct connection (no proxy) passes the check regardless of origin.

Use `getConnInfo` from `hono/bun` to read the actual socket remote address instead of trusting client-supplied headers.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

8 issues found across 14 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/docs/client/src/content/draft/pt-br/introduction.mdx">

<violation number="1" location="apps/docs/client/src/content/draft/pt-br/introduction.mdx:31">
P3: The quickstart command now conflicts with its own heading (`npx` vs `bunx`), which can confuse users following the setup instructions.</violation>
</file>

<file name="apps/mesh/src/cli.ts">

<violation number="1" location="apps/mesh/src/cli.ts:64">
P2: CLI help text now points users to `bunx decocms`, which conflicts with the documented `npx decocms` entrypoint and can misdirect users without Bun installed.</violation>
</file>

<file name="apps/docs/client/src/content/latest/en/introduction.mdx">

<violation number="1" location="apps/docs/client/src/content/latest/en/introduction.mdx:32">
P2: The quickstart command now contradicts the `(npx)` option label and documented onboarding path; this may block users without Bun installed. Keep this command as `npx decocms` (or rename the option to Bun explicitly).</violation>
</file>

<file name="apps/docs/client/src/content/latest/pt-br/mcp-mesh/quickstart.mdx">

<violation number="1" location="apps/docs/client/src/content/latest/pt-br/mcp-mesh/quickstart.mdx:16">
P3: The quickstart instruction is inconsistent: the section says "(npx)" but the command uses `bunx`, which can confuse users about the expected tool.</violation>
</file>

<file name="apps/docs/client/src/content/latest/pt-br/introduction.mdx">

<violation number="1" location="apps/docs/client/src/content/latest/pt-br/introduction.mdx:32">
P2: The quick-start command was changed to `bunx decocms`, which conflicts with the documented `npx` flow and adds an unintended Bun prerequisite for users.</violation>
</file>

<file name="apps/docs/client/src/content/latest/en/mcp-mesh/quickstart.mdx">

<violation number="1" location="apps/docs/client/src/content/latest/en/mcp-mesh/quickstart.mdx:16">
P3: The quickstart command conflicts with the surrounding "(npx)" instructions; use `npx decocms` here to keep the documented setup path consistent.</violation>
</file>

<file name=".github/workflows/release.yaml">

<violation number="1" location=".github/workflows/release.yaml:154">
P2: The release output’s “Install via npm” command was changed to `bunx`, which requires Bun and conflicts with npm-targeted install instructions. Keep npm instructions on `npx` to avoid breaking copy/paste setup for npm users.</violation>
</file>

<file name="apps/docs/client/src/content/draft/pt-br/mcp-mesh/quickstart.mdx">

<violation number="1" location="apps/docs/client/src/content/draft/pt-br/mcp-mesh/quickstart.mdx:16">
P3: The command now contradicts the section label `(npx)`, which can mislead users about which runner to use. Keep this line consistent with the documented option.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[vibegui]

@cubic-dev-ai anything else?

[cubic-dev-ai]

@cubic-dev-ai anything else?

@vibegui The core logic for the zero-ceremony setup is robust, especially the security boundary around the local session endpoint. I have a few minor observations for scripts/dev.ts to ensure it's as flexible as the CLI:

• Respect existing DATABASE_URL: In apps/mesh/scripts/dev.ts, you’re currently hard-overwriting process.env.DATABASE_URL. To align with the logic you added to the CLI, it should probably respect an existing environment variable if the user is explicitly pointing to a different database for development:

  process.env.DATABASE_URL = process.env.DATABASE_URL ?? `file:${join(meshHome, "mesh.db")}`;

• Cross-platform path handling: In dev.ts, the line import.meta.dir.replace("/scripts", "") might be brittle on Windows if Bun provides backslashes in the path. Using join(import.meta.dir, "..") or a more robust path utility would be safer.
• Seeding Gate: The use of waitForSeed() in the /local-session route is a great addition. It effectively prevents the "500 on first load" race condition that often plagues auto-login implementations where the DB isn't fully ready yet.
• Loopback Check: Using getConnInfo (socket-level IP) instead of headers is the correct way to secure this. The inclusion of the IPv4-mapped IPv6 loopback (::ffff:127.0.0.1) is also a nice catch for compatibility.

The move to track the NATS and OpenRouter onboarding in DEBT.md is also a good call to keep this PR's scope focused while ensuring those UX improvements aren't forgotten.

AI Review Settings | Manage Learnings | Documentation

[cubic-dev-ai]

4 issues found across 7 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/src/index.ts">

<violation number="1" location="apps/mesh/src/index.ts:38">
P1: Use an explicit boolean-string check for `MESH_ALLOW_LOCAL_PROD`; the current truthiness check can unintentionally allow local mode in production.</violation>

<violation number="2" location="apps/mesh/src/index.ts:103">
P2: Handle local-mode module import failure as fatal (or otherwise resolve the seed gate); currently failures can leave `waitForSeed()` unresolved and break local-session auth.</violation>
</file>

<file name="apps/mesh/scripts/dev.ts">

<violation number="1" location="apps/mesh/scripts/dev.ts:36">
P1: Non-interactive runs can incorrectly use `~/deco` instead of the CI-safe `.mesh-dev` path.</violation>
</file>

<file name="packages/mesh-sdk/src/lib/mcp-oauth.ts">

<violation number="1" location="packages/mesh-sdk/src/lib/mcp-oauth.ts:560">
P2: Using getOAuthRedirectOrigin() as the postMessage target in local dev can break OAuth callbacks behind proxies, because the opener origin (e.g. proxy.localhost) won’t match the redirect origin (localhost). The message is dropped when targetOrigin mismatches, so the parent window never receives the OAuth code. Keep the permissive target for local dev or otherwise ensure the target matches the opener’s origin.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}