⚡ OpenAI Codex SDKcodex (default)
Native @openai/codex-sdk integration supporting thread resumption (resume_thread_id), reasoning_effort, token budgets, and read-only vs workspace-write sandboxes.
10 Tools · 1 Approval Gate · 1-Min GHCR Deploy · 4 Pluggable Agent Drivers · bwrap FS/Net Jail
Named GeminiBastionMCP because it conquered Web Gemini's strict OAuth 2.1 DCR & 16-redirect-URI requirements first — while speaking 100% standard MCP 2025-11-25 Streamable HTTP for Claude.ai, ChatGPT, and Cursor. Deploy in 1 minute from pre-built GHCR images with bubblewrap per-workspace isolation and pluggable Codex, Claude Code, Gemini CLI, or OpenCode background agents.
Connecting Web Gemini (gemini.google.com), Claude.ai, or ChatGPT to real repositories and infrastructure usually breaks down on strict OAuth 2.1 DCR handshakes, 40-tool approval popups, or raw secret exposure.
| Capability | GeminiBastionMCP (v0.2.0) | Generic MCP Proxies (MetaMCP) | Official Remote MCPs (GitHub/CF) | Local Stdio Shell MCPs |
|---|---|---|---|---|
| Web Gemini, Claude.ai & ChatGPT OAuth 2.1 DCR + SSO | ✅ Native for all 3 (RFC 9728/8414/8707, 16 redirect URIs, 8KB state, 60s grace + Google/GitHub SSO) | ⚠️ Often lacks RFC 8707 resource binding or 8KB state | ✅ Single-vendor only | ❌ Desktop stdio only |
| Web Chat Approval UX | ✅ 10 Tools, 1 Approval Gate (Tools 1–9 safe for Always Allow; only #10 writes externally) | ❌ Exposes 30–60 granular tools; constant popup fatigue | ⚠️ Mixed read/write tools | ❌ Confirm every shell call or run unguarded |
| Pluggable Background Coding Agents & Job Promotion | ✅ 4 Drivers (@openai/codex-sdk, Claude Code, Gemini CLI, OpenCode) + 15s auto-job promotion | ❌ Router only, no workspace sandbox | ❌ REST API wrapper only, cannot run tests | ⚠️ Single local shell with no background job promotion |
| Per-Workspace bwrap Jail & Zero Secret Leakage | ✅ bwrap FS/network jail (--unshare-net) + UID 1001/1002 + SecretScrubber + isolated-runner sidecar | ❌ Depends on downstream server | ✅ Cloud-hosted | ❌ Subprocesses inherit host filesystem & secrets |
| Two-Phase Infrastructure Mutation (Plan → Apply) | ✅ stage_mutation_plan (15m TTL + rollback snapshot) → publish_changes | ❌ Direct write pass-through | ❌ Immediate external writes | ❌ None |
Switch between OpenAI Codex SDK, Claude Code CLI, Gemini CLI, or OpenCode CLI per job via agent_driver (or set DEFAULT_AGENT_DRIVER). Every write run automatically creates a pre-run GIT_INDEX_FILE snapshot and executes either in-container under UID 1002 or inside a dedicated isolated-runner sidecar container.
Native @openai/codex-sdk integration supporting thread resumption (resume_thread_id), reasoning_effort, token budgets, and read-only vs workspace-write sandboxes.
Headless Claude Code CLI driver (claude -p --output-format json) with strict read-only tool allowlisting in agent_readonly mode and scoped ANTHROPIC_API_KEY injection.
Headless Google Gemini CLI driver (gemini -p) for autonomous repository analysis and multi-file refactoring with scoped GEMINI_API_KEY injection and SecretScrubber protection.
OpenCode CLI driver (opencode run) enabling multi-provider open-source coding agent workflows inside the same checkpointed /workspaces/{slug} sandbox.
Stateless Streamable HTTP transport mounted on Hono (/mcp) with UID 1001/1002 separation, bubblewrap per-workspace filesystem & network namespaces, authenticated ops-mcp sidecar proxy, and optional isolated-runner container.
Filter the 10-tool surface by permission tier. Configure Tools 1–9 as "Always Allow" in Web Gemini, Claude.ai, or ChatGPT for zero-popup autonomous exploration, coding, and staging — keeping Tool #10 (publish_changes) as your single human-in-the-loop approval gate.
Toggle between the zero-leakage Public Gateway Portal served at GET / and the mobile-installable Operator Cockpit PWA served at /admin.
Objective: Refactor rate limiter middleware and run L0/L1 vitest suite --- [12 checkpoint] Created non-destructive GIT_INDEX_FILE snapshot refs/mcp-checkpoints/cp_20261121_01 [13 driver:claude_code] Applied atomic hunk to src/auth/rateLimiter.ts [14 validate] L0 tsc --noEmit passed (0 errors) | L1 vitest passed
Engineered so you can safely connect Web Gemini, Claude.ai, and ChatGPT to real GitHub repositories, Cloudflare accounts, and internal infrastructure.
On Linux/Docker, workspace_exec wraps subprocesses in bubblewrap (bwrap), mounting only /workspaces/{slug} (hiding sibling workspaces) and defaulting to --unshare-net (offline network namespace unless allow_network: true is passed).
gateway runs as UID 1001 owning /data (mode 0700 SQLite WAL DB), while worker runs as UID 1002. Optionally offload all agent drivers to a dedicated isolated-runner container sidecar via AGENT_RUNNER_URL + Bearer token.
buildSandboxedEnv() strips all gateway credentials from child processes. Downstream MCP-2 sidecars (ops-mcp) require per-request Authorization: Bearer tokens (OPS_MCP_AUTH_TOKEN) and fail closed if misconfigured.
Before every code_patch, codex_write, or agent_write run, the gateway snapshots tracked and untracked files into refs/mcp-checkpoints/* using a temporary GIT_INDEX_FILE without touching your real .git/index or HEAD.
Direct pushes to main, master, or default_branch are physically rejected. Cloudflare and downstream MCP-2 mutations must be staged via stage_mutation_plan (15m TTL + rollback payload) before publish_changes executes them.
Supports PKCE (S256), RFC 8707 Resource Indicators, 60s refresh token family rotation, untrusted prompt-injection boundaries, plus fail-closed Google & GitHub OAuth operator login.
Pull pre-built multi-arch images directly from GitHub Container Registry (choose :lite ~300MB for fast Node/TS/Git + bwrap, or :full with Python/uv/ripgrep/ast-grep/Codex/Claude Code/Gemini CLI/OpenCode), then paste your /mcp endpoint into Web Gemini, Claude.ai, or ChatGPT.
# Option A: Lightweight image (~300MB, Node 22 + Git + bubblewrap) docker pull ghcr.io/kaiserunix/gemini-bastion-mcp:lite # Option B: Full Polyglot + Multi-Agent CLI image (includes Python/uv, ripgrep, ast-grep, Codex/Claude/Gemini/OpenCode CLIs) docker pull ghcr.io/kaiserunix/gemini-bastion-mcp:full # Generate ADMIN_PASSWORD_HASH (scrypt:: ) & OAUTH_SIGNING_SECRET: node -e 'const c=require("node:crypto"),s=c.randomBytes(16).toString("hex");console.log(`ADMIN_PASSWORD_HASH=scrypt:${s}:${c.scryptSync(process.argv[1],s,32,{N:16384,r:8,p:1}).toString("hex")}`)' 'your-strong-operator-password' node -e 'console.log("OAUTH_SIGNING_SECRET=" + require("node:crypto").randomBytes(32).toString("hex"))'
git clone https://github.com/Kaiserunix/gemini-bastion-mcp.git cd gemini-bastion-mcp cp .env.example .env # Edit .env: set PUBLIC_DOMAIN, ADMIN_PASSWORD_HASH, OAUTH_SIGNING_SECRET, DEFAULT_AGENT_DRIVER=codex # Start core stack (or add --profile ops --profile isolated-runner): docker compose -f docker/docker-compose.yml up -d
# Universal MCP Streamable HTTP Endpoint (OAuth 2.1 DCR auto-discovers /.well-known/*): https://mcp.yourdomain.com/mcp # Recommended Client Tool Permission Policy: # - Tools 1..9 (workspace_manage .. stage_mutation_plan) -> Always Allow (0 popups) # - Tool 10 (publish_changes) -> Ask Before Running (Single Write Gate)