MindStudio Local Tunnel

Local tunnel for MindStudio. Use your own locally-running AI models, develop v2 apps with live preview, and edit custom interfaces and scripts — all from your own machine.

Quick Start

macOS / Linux (Standlone Binary)

No dependencies required — this downloads a standalone binary:

curl -fsSL https://msagent.ai/install-tunnel.sh | bash
mindstudio-local

To update, run the same command again. To uninstall, rm /usr/local/bin/mindstudio-local.

The app will also prompt you to update automatically when a new version is available.

Windows (PowerShell)

No dependencies required — this downloads a standalone binary:

irm https://msagent.ai/install-tunnel.ps1 | iex
mindstudio-local

To update, run the same command again. To uninstall, delete %USERPROFILE%\.mindstudio\bin\mindstudio-local.exe.

The app will also prompt you to update automatically when a new version is available.

Alternative: Install via npm (all platforms)

npm install -g @mindstudio-ai/local-model-tunnel
mindstudio-local

The app will walk you through connecting your MindStudio account and getting set up.

Features

Apps v2 Local Dev Mode

Develop MindStudio Apps v2 locally with instant feedback. The CLI detects your mindstudio.json, starts a dev session, and gives you live preview with real auth, databases, and method execution — all running on your machine.

cd my-app          # must contain mindstudio.json with "appId"
mindstudio-local

What happens:

1. The CLI reads mindstudio.json and enters dev mode automatically
2. Installs dependencies if needed (npm install in method/frontend dirs)
3. Starts your frontend dev server (Vite, webpack, etc.)
4. Connects to the MindStudio platform and syncs your table schemas
5. Starts a local proxy that serves your frontend with platform context injected
6. Polls for method execution requests and runs them locally (transpiled on the fly)

The TUI shows:

• Session status, branch, and preview URL
• Tabbed views: Info, Requests, Methods, Dev Server logs
• Schema sync results
• Live method execution log with timing and errors

Key details:

• Methods are transpiled with esbuild and executed in isolated Node.js child processes
• @mindstudio-ai/agent SDK works identically — database queries, auth checks, etc. all go through the real platform
• The local proxy injects window.__MINDSTUDIO__ into HTML so the frontend SDK works
• Changes to mindstudio.json trigger an automatic session restart
• Frontend HMR works through the proxy (WebSocket upgrades are forwarded)

Headless Mode

Run the dev tunnel without a TUI for programmatic control. Designed for hosted sandboxes, CI pipelines, or any automation that needs the tunnel as a background service.

mindstudio-local --headless --port 5173 --bind 0.0.0.0

Headless mode does NOT start a dev server — the caller manages that separately. The --port flag tells the tunnel which port to proxy to.

CLI Flags

mindstudio-local --headless [options]

Options:
  --headless            Run without TUI, output JSON events to stdout
  --port <n>            Dev server port to proxy to (default: from web.json)
  --proxy-port <n>      Preferred proxy port (default: auto from app ID)
  --bind <addr>         Proxy bind address (default: 127.0.0.1)
  --log-level <level>   Log verbosity: error, warn, info, debug (default: info)

JSON Event Protocol

Stdout emits newline-delimited JSON events — one object per line:

| Event | Key Fields | When | |-------|-----------|------| | starting | appId, name | Initializing | | session-started | sessionId, branch, proxyPort, proxyUrl | Session active, proxy running | | schema-synced | created, altered, errors | Table schema synced | | method-start | id, method | Method execution received | | method-complete | id, success, duration, error? | Method execution finished | | connection-warning | message | Lost platform connection | | connection-restored | | Reconnected | | session-expired | | Platform expired session (exits with code 1) | | error | message | Fatal error | | stopping | | Graceful shutdown initiated | | stopped | | Cleanup complete, exiting |

Spawning from a Parent Process

const { spawn } = require('child_process');

const tunnel = spawn('mindstudio-local', [
  '--headless', '--port', '5173', '--bind', '0.0.0.0'
], {
  cwd: '/path/to/app',
  stdio: ['ignore', 'pipe', 'pipe'],
});

// JSON events from stdout
let buffer = '';
tunnel.stdout.on('data', (chunk) => {
  buffer += chunk.toString();
  let idx;
  while ((idx = buffer.indexOf('\n')) !== -1) {
    const event = JSON.parse(buffer.slice(0, idx));
    buffer = buffer.slice(idx + 1);

    if (event.event === 'session-started') {
      console.log('Preview:', event.proxyUrl);
    }
  }
});

// Structured logs from stderr
tunnel.stderr.on('data', (chunk) => {
  console.error('[tunnel]', chunk.toString().trimEnd());
});

// Graceful shutdown
process.on('SIGTERM', () => tunnel.kill('SIGTERM'));

Programmatic API

import { startHeadless } from '@mindstudio-ai/local-model-tunnel';

await startHeadless({
  cwd: '/path/to/app',
  devPort: 5173,
  bindAddress: '0.0.0.0',
  logLevel: 'debug',
});

Logging

The tunnel has structured logging throughout — API call timing, method execution lifecycle, transpilation, proxy requests, connection state, and errors.

Headless mode: logs go to stderr at info level by default. Stdout is reserved for the JSON event protocol. Override with --log-level:

mindstudio-local --headless --log-level debug  # verbose logs on stderr

Interactive (TUI) mode: logs go to .mindstudio-dev.log in the working directory at error level by default. This keeps logs out of the terminal UI.

Log format:

[2026-03-14T12:34:56.789Z] INFO  api POST /dev/manage/start → 200 (142ms) {"sessionId":"848583c4","branch":"main"}
[2026-03-14T12:34:57.012Z] INFO  runner Request received {"requestId":"req-1","method":"getDashboard"}
[2026-03-14T12:34:57.024Z] INFO  transpiler Transpiled in 12ms {"methodPath":"dist/methods/src/getDashboard.ts"}
[2026-03-14T12:34:57.089Z] INFO  runner Request complete {"requestId":"req-1","success":true,"duration":77}

Log levels:

| Level | What you get | |-------|-------------| | error | Failures only — 403s, timeouts, crashes | | warn | Errors + connection issues, port conflicts, invalid output | | info | Warnings + API timing, request lifecycle, session state changes | | debug | Everything — child process details, config resolution, proxy requests, transpile paths |

Local Model Tunnel

Connect local AI providers to MindStudio Cloud so you can use your own hardware for text, image, and video generation.

| Provider | Capability | Website | | --------------------------------------------------------------------------------- | ---------------- | ----------- | | Ollama | Text generation | ollama.com | | LM Studio | Text generation | lmstudio.ai | | Stable Diffusion WebUI | Image generation | github.com | | ComfyUI | Video generation | comfy.org |

Don't have any of these installed yet? No problem -- select Manage Providers in the app for step-by-step setup guides for each one.

How it works:

1. You start a local provider (e.g. ollama serve)
2. The tunnel detects it and discovers your models
3. You sync your models to MindStudio Cloud
4. When a MindStudio app uses one of your models, the request is routed to your local machine and the response is streamed back

The tunnel stays running and handles requests as they come in. You can see live request logs and status in the dashboard.

Local Interface & Script Editing

Edit custom interfaces (SPAs) and scripts from your MindStudio apps locally. Open any app that's active in the MindStudio editor, clone its interfaces or scripts to your machine, and develop with a local dev server — complete with hot reloading for interfaces.

How it works:

1. Open an app in the MindStudio editor
2. Select Interfaces in the CLI dashboard
3. Pick an interface or script from your app
4. The CLI clones the scaffold and starts a local dev server
5. Edit with your preferred tools — the CLI provides ready-to-use commands for Claude Code and Codex

Development

npm install
npm run build           # Build with tsup
npm run dev             # Build + run CLI
npm run local-update    # Build + npm link for local testing

Install from a branch

npm i -g mindstudio-ai/mindstudio-local-model-tunnel#branch-name

The prepare script runs npm run build automatically after clone.

Configuration

Credentials are stored in ~/.mindstudio-local-tunnel/config.json. The config supports two environments (prod and local) with separate API keys and base URLs.

The TUI's onboarding flow handles initial setup. For headless/sandbox use, write the config file directly:

{
  "environment": "prod",
  "environments": {
    "prod": {
      "apiKey": "sk_...",
      "userId": "...",
      "apiBaseUrl": "https://api.mindstudio.ai"
    }
  }
}

Want a New Provider?

If there's a local AI tool you'd like to use with MindStudio, open an issue to request it. Or if you're feeling adventurous, add it yourself -- each provider is a self-contained directory under src/providers/ and the CLAUDE.md file has a full guide for adding one. PRs welcome!

License

MIT