VibeBridge

A secure local bridge between Gemini Spark and your development workspace.

Give an AI agent controlled access to your files, codebase, and terminal without handing it unrestricted access to your machine.

Overview

VibeBridge is a local runtime and desktop interface that exposes a developer's selected workspace to Gemini Spark through the Model Context Protocol (MCP).

Think of it as a controlled execution layer:

• Gemini Spark handles reasoning and decides which tools it needs.

• VibeBridge performs those actions locally.

• The security layer keeps file operations inside the selected workspace.

• The permission layer lets the user control writes and command execution.

VibeBridge is not an LLM or agent framework. It is the local bridge that gives an external AI agent access to a real development environment.

Related MCP server: lnwjud

Why VibeBridge?

AI coding tools are most useful when they can actually work with a project: inspect files, search a codebase, modify source files, and run commands.

The problem is trust. Giving an AI unrestricted access to a computer is a bad security boundary.

VibeBridge is designed around a narrower model:

Expose one workspace, provide explicit tools, enforce a filesystem boundary, and keep sensitive actions behind permissions.

What it provides

Architecture

flowchart LR
    A[Gemini Spark] <-->|MCP / HTTPS| B[Public Tunnel]
    B <--> C[VibeBridge Runtime]

    C --> D[MCP Server]
    C --> E[Permission Manager]
    C --> F[Security Sandbox]
    C --> G[Activity Logger]

    F --> H[Filesystem Tools]
    F --> I[Terminal Executor]
    H --> J[(Selected Workspace)]
    I --> J

The main packages are separated by responsibility:

VibeBridge
├── apps/
│   └── desktop/          # React + TypeScript + Tauri desktop UI
├── packages/
│   ├── mcp-server/       # MCP transport, server, tools and tunnel handling
│   ├── security/         # Workspace sandbox and permission policy
│   └── shared/           # Shared types, schemas and contracts
└── tests/                # Security, permission and integration tests

Request flow

1. Gemini Spark connects to VibeBridge through the MCP endpoint.

2. VibeBridge validates the requested tool and its arguments.

3. Filesystem paths are resolved against the selected workspace.

4. Sensitive write/execute operations are passed through the permission policy.

5. The tool executes locally and returns a structured MCP response.

6. Activity is logged by the runtime.

Security Model

Security is one of the core design goals of VibeBridge.

Workspace sandbox

File operations are resolved against the canonical workspace path rather than relying on string-prefix checks. This is intended to prevent common traversal and symlink-escape scenarios.

Permission tiers

Available permission modes are:

• prompt — ask before writes and command execution

• auto_approve_read — automatically allow reads, prompt for writes and execution

• auto_approve_all — automatically allow all actions

• deny_writes — read-only mode; reject writes and commands

Safer file editing

edit_file works with an exact old_text match. If the expected text is not found, the edit fails instead of silently modifying the wrong location.

Command limits

Command execution uses the selected workspace as cwd, supports configurable timeouts, and caps command output to reduce the impact of runaway processes or extremely large logs.

Important: VibeBridge is a security boundary, not a guarantee that arbitrary AI-generated commands are safe. Review your tunnel configuration, permission mode, and commands before enabling broad access.

MCP Tools

VibeBridge currently exposes eight tools:

Quick Start

Prerequisites

• Node.js 18+

• npm 9+

• ngrok account and auth token when using the ngrok tunnel

• Rust and Cargo when building/running the native Tauri shell

1. Clone

git clone https://github.com/assishmoncs/vibebridge.git
cd vibebridge

2. Install dependencies

npm install

3. Configure the environment

cp .env.example .env

A minimal configuration looks like:

PORT=3000
HOST=127.0.0.1
VIBEBRIDGE_WORKSPACE=/absolute/path/to/your/project

ENABLE_TUNNEL=true
TUNNEL_PROVIDER=ngrok
NGROK_AUTHTOKEN=your_ngrok_auth_token

PERMISSION_MODE=prompt

4. Build the project

npm run build

5. Run VibeBridge

For the desktop development UI:

npm run dev:desktop

For the server/runtime:

npm start

Or run the Tauri desktop shell:

npm run tauri dev

Once the runtime is running, use the MCP endpoint shown by VibeBridge to connect Gemini Spark.

Tunnel Configuration

VibeBridge supports a pluggable tunnel configuration through environment variables.

ngrok

ENABLE_TUNNEL=true
TUNNEL_PROVIDER=ngrok
NGROK_AUTHTOKEN=your_ngrok_auth_token

VibeBridge can then expose the local MCP server through an HTTPS endpoint suitable for a remote client.

Direct mode

The environment configuration also supports a direct tunnel provider when the surrounding network setup already provides the required connectivity.

Development

Useful commands

Testing

npm test

The repository includes tests for permission handling, filesystem/security behavior, editing, command execution, and MCP-related integration behavior.

Project Status

VibeBridge is currently at v0.1.0 and is actively evolving.

Implemented

• Streamable HTTP MCP transport

• Workspace-scoped filesystem sandbox

• Canonical path / symlink escape checks

• Exact-match file editing

• Command execution with timeout and output limits

• Permission management for read, write, and execute operations

• React + Tauri desktop interface

• Configurable HTTPS tunnel provider

Planned

• Visual Git diff inspection

• Cloudflare Quick Tunnel support

• Workspace indexing and symbol search

• Further desktop UX improvements

Contributing

Contributions are welcome.

A good starting point is to keep changes focused within the existing package boundaries:

• apps/desktop for the UI

• packages/mcp-server for MCP/runtime behavior

• packages/security for sandboxing and permission logic

• packages/shared for shared contracts and schemas

Before opening a pull request, run:

npm test
npm run build

License

VibeBridge is released under the MIT License.

VibeBridge — controlled local execution for AI-powered development.