Skip to main content
Glama

Gemini Space

English · 简体中文

CI License: MIT Node.js >= 22.19

Give Google Gemini Web (and its parallel Task subagents) your local machine—speaking the exact Antigravity (agy) tool surface Gemini was trained on.


Why Gemini Space?

Most local coding MCP servers (Desktop Commander, DevSpace, Filesystem MCP) were designed around ChatGPT / Codex (exec_command, write_stdin, apply_patch, open_workspace) or Claude Code. When you connect them to Gemini Web (gemini.google.com → Custom Connectors), you hit two walls:

  1. Wrong tool distribution: Gemini models are post-trained heavily on Google Antigravity's PascalCase tool surface (read_file, write_file, edit_file, run_command, manage_task) with absolute paths and zero open_workspace ceremony.

  2. Gemini Web Connector protocol quirks:

    • Strict JSON Schema subset: Connector registration fails ("We had trouble connecting") if inputSchema contains $schema, additionalProperties, $defs, const, or >32-bit integer bounds.

    • ~60s hard RPC timeout & no MCP Tasks: Gemini Web declares MCP 2025-11-25 without tasks capability, ignores post-turn server push notifications, and kills any tool call exceeding ~60s (DEADLINE_EXCEEDED).

    • Parallel Task Subagents: In Gemini Task mode, Gemini spawns multiple cloud subagents that simultaneously initialize against your /mcp endpoint. Without session isolation and concurrent refresh-token rotation grace, subagents either block each other past 60s, leak background task notices across agents, or trigger 401 token-rotation races.

Gemini Space is a lightweight, self-hosted MCP server built from the ground up around those exact constraints—with zero closed-source binary dependencies (only 6 runtime npm packages + Node's built-in node:sqlite).


Related MCP server: VBridge

Key Features

  • 5 Native Deterministic agy Tools (Pure Node.js)

    • read_file: 800-line / 46,080-byte paginated text reads with UTF-8 safe ByteOffset continuation + magic-byte multimodal inline blocks (PNG, JPEG, GIF, WebP, PDF, MP3, WAV, MP4).

    • write_file: Automatic parent directory creation, Overwrite, and newline-aware Append while preserving file mode bits.

    • edit_file: EOL-normalized (LF / CRLF / mixed) exact replacement across occurrences with LCS (+A/-R lines) diff summaries and per-file write locks.

    • run_command: Real 80×24 PTY execution (zsh -c), inheriting your real HOME (~/.ssh, ~/.gitconfig), ANSI stripping, and 10 KiB head/tail truncation with full output saved on disk.

    • manage_task: list, status, send_input (interactive PTY stdin), and orphan-free process-group + descendant SIGKILL (kill).

  • 45-Second Smart Hold (Bridging Gemini's 60s Ceiling)

    • Non-daemon run_command calls automatically hold on the server for up to 45s—commands under 45s finish in one round trip.

    • Commands exceeding 45s return a TaskId; each manage_task(Action: "status") call holds up to another 45s until completion, preserving the real exit code and output.

  • Built for Gemini Task Multi-Subagent Concurrency

    • Issues soft Mcp-Session-Id headers on initialize (1 Gemini Subagent ↔ 1 isolated task/notice queue), executes commands across subagents truly in parallel, and never 404s stale sessions across local server restarts.

  • Code Mode (execute / poll_execution / cancel_execution)

    • Run an async JavaScript snippet on your machine calling tools.read_file, tools.edit_file, tools.run_command in loops or Promise.all—collapsing 20+ operations into a single Gemini tool call.

  • Automatic Local Skills Injection

    • Scans ~/.agents/skills, ~/.claude/skills, ~/.codex/skills, and ~/.devspace/skills (SKILL.md) into MCP instructions (injected directly into Gemini Web's system prompt).

  • OAuth 2.1 + /web/ Activity Dashboard

    • Single-owner password approval page, SHA-256 hashed SQLite token store with a 300-second refresh-token rotation grace window, built-in Gemini Schema sanitizer, and a zero-build /web/ UI to inspect every subagent session and tool call.


Architecture

flowchart LR
  subgraph Gemini Web / Gemini Task
    SA1["Main Agent / Subagent A\n(Mcp-Session-Id: S1)"]
    SA2["Subagent B\n(Mcp-Session-Id: S2)"]
  end

  Tunnel["HTTPS Tunnel\n(Tailscale Funnel / Cloudflare)"]

  subgraph Gemini Space (Local Mac / Linux)
    Auth["OAuth 2.1 + 300s Refresh Grace\n+ Gemini Schema Sanitizer"]
    Router["Soft Session Router\n(S1 / S2 Isolated Queues)"]
    Engine["Deterministic AGY Engine\n(80x24 PTY · 45s Hold · Multimodal FS)"]
    CM["Code Mode VM\n(execute / poll / cancel)"]
    Web["/web/ Activity UI"]
  end

  SA1 & SA2 -- "HTTPS POST /mcp" --> Tunnel --> Auth --> Router
  Router --> Engine & CM
  Router -. "SQLite audit" .-> Web

5-Minute Quickstart

1. Prerequisites

  • Node.js >= 22.19 (uses built-in node:sqlite) and pnpm

  • macOS or Linux

  • An HTTPS tunnel pointing to your local port 7676 (e.g., Tailscale Funnel or Cloudflare Tunnel)

2. Clone & Build

git clone https://github.com/cunninghamcard-bit/gemini-space.git
cd gemini-space
pnpm install
pnpm build

3. Initialize & Start Tunnel

# Expose local port 7676 over HTTPS (example using Tailscale Funnel):
tailscale funnel --bg 7676

# Initialize ~/.devspace/config.jsonc and generate your Owner Password in ~/.devspace/auth.json:
./bin/gemini-space.js init --public-url https://your-machine.your-tailnet.ts.net

# Verify everything is ready:
./bin/gemini-space.js doctor

# Start the server:
./bin/gemini-space.js serve

Tip: Your generated Owner Password is saved in ~/.devspace/auth.json (ownerToken). You will enter it once when authorizing Gemini Web or signing into https://<your-host>/web/.

4. Connect to Google Gemini Web

  1. Open gemini.google.com/customize/connectors → click + Custom.

  2. Enter your MCP Server URL:

    https://your-machine.your-tailnet.ts.net/mcp

    (Leave Client ID / Secret blank — Gemini Space supports dynamic OAuth client registration.)

  3. Approve the connection using your Owner Password from ~/.devspace/auth.json.

  4. Open a chat (or Gemini Task) and start coding directly against your local repositories!

⚠️ Important Google Connector Caveat: Google binds custom connectors by hostname (*.your-tailnet.ts.net). Do not register a second test connector on the same hostname (even on a different port like :8443), or Google will overwrite/revoke the shared OAuth account link. Always use a separate hostname (e.g., *.trycloudflare.com) if testing another MCP server alongside production.


Running as a Background Service (launchd on macOS)

Create ~/Library/LaunchAgents/dev.gemini-space.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>dev.gemini-space.server</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/node</string>
    <string>--import</string>
    <string>/ABSOLUTE/PATH/TO/gemini-space/bin/silence-sqlite-warning.js</string>
    <string>/ABSOLUTE/PATH/TO/gemini-space/dist/cli.js</string>
    <string>serve</string>
  </array>
  <key>WorkingDirectory</key><string>/ABSOLUTE/PATH/TO/gemini-space</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    <key>HOME</key><string>/Users/YOUR_USERNAME</string>
  </dict>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/Users/YOUR_USERNAME/.devspace/logs/gemini-space.out.log</string>
  <key>StandardErrorPath</key><string>/Users/YOUR_USERNAME/.devspace/logs/gemini-space.err.log</string>
</dict>
</plist>

Load it:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.gemini-space.server.plist

Configuration (~/.devspace/config.jsonc)

{
  "configVersion": 1,
  "server": {
    "host": "127.0.0.1",
    "port": 7676,
    "publicBaseUrl": "https://your-machine.your-tailnet.ts.net"
  },
  "agy": {
    "workspace": "~",
    "holdMs": 45000,
    "exposedTools": ["read_file", "write_file", "edit_file", "run_command", "manage_task"]
  },
  "codeMode": {
    "enabled": true
  },
  "skills": {
    "enabled": true,
    "paths": []
  },
  "ui": {
    "enabled": true
  },
  "activity": {
    "enabled": true,
    "maxCalls": 500
  },
  "oauth": {
    "refreshTokenGraceSeconds": 300
  }
}

CLI Reference

gemini-space serve                        # Start OAuth + MCP + /web/ server
gemini-space doctor                       # Verify config, OAuth DB, discovered skills & tools
gemini-space init --public-url <https>    # Initialize config.jsonc and Owner Password
gemini-space config show                  # Print resolved configuration
gemini-space config set codeMode.enabled false

Acknowledgements & License

Originally forked from @waishnav/devspace for its clean OAuth 2.1 SQLite foundation, then stripped of ~79k lines of legacy surfaces and rebuilt around a pure Node.js deterministic Antigravity tool engine tailored for Google Gemini Web.

Licensed under the MIT License.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables authorized remote MCP clients to securely reach local Mac or Windows tools over OAuth, including shell commands, file read/write, background jobs, screenshots, UI control, and clipboard access. It can also expose configured Desktop MCP servers and optional Claude Code task delegation.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables web-based AI clients such as Claude, ChatGPT, Grok, and Postman to securely operate a local machine through a single OAuth-gated MCP endpoint exposing 38 governed tools. Covers file read/write/edit, whitelisted shell commands, search, Git, SQLite, browser automation, DevTools, background tasks, localhost fetching, clipboard, notifications, port management, and Postman control.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables web-based AI clients like Claude, ChatGPT, and Grok to securely operate a local machine through OAuth-gated MCP tools covering files, shell, Git, databases, browser automation, and background tasks.
      MIT