
gemini-bastion-mcp
io.github.Kaiserunix/gemini-bastion-mcp
OAuth 2.1 MCP bastion for Web Gemini, Claude & ChatGPT: 10 tools, 1 gate, bwrap & multi-agent.
Documentation
GeminiBastionMCP (gemini-bastion-mcp)
Built for Web Gemini (gemini.google.com) Connected Apps, Claude.ai Custom Connectors & ChatGPT MCP Connectors — NOT Gemini-Only.
English | 简体中文
Live Showcase · Why This Exists · Architecture · 10 Tools & Memory · Gem Prompt & MCP Prompts · CI Watchdog · Quick Start · Security v2 · MCP Registry · Docs
- 100% Standard Remote MCP for Web Gemini, Claude.ai & ChatGPT: Named
GeminiBastionMCPbecause it conqueredgemini.google.comConnected Apps' strict OAuth 2.1 DCR rules first (16 redirect URIs, 8KBstate, RFC 8707/9728) — while speaking pure MCP 2025-11-25 Streamable HTTP for Claude.ai Custom Connectors, ChatGPT MCP Connectors, Cursor & MCP Inspector. - Code, Test & Deploy from Mobile or Any Browser: Sync GitHub repos, explore AST/files (
ripgrep,ast-grep,repomix), apply atomic multi-file patches, and run L0/L1/L2 checks inside a per-workspacebwrapFS & network jail (--unshare-netby default). - Pluggable Multi-Agent Drivers & 1-Gate Blast Radius: Delegate background tasks to OpenAI Codex SDK, Claude Code CLI, Gemini CLI, or OpenCode CLI (
workspace_execauto-promotes after 15s), with zero gateway secret leakage and every external write funneled through one single approval gate (publish_changes).
[!TIP] Skip the build! Pull pre-built multi-variant GHCR images (
ghcr.io/kaiserunix/gemini-bastion-mcp:lite~350MB or:full) and launch in under 60 seconds withdocker compose pull && docker compose up -d.
What a 60-Second Mobile Prompt-to-PR Looks Like
You (on phone in Web Gemini): "Check why CI failed on PR #42, fix the bug, run tests, and open a fix PR."
github_inspect(Tier 1 · Always Allow) — Fetches failed Actions logs wrapped in an untrusted-data boundary.workspace_manage+code_explore(Tier 1 · Always Allow) — Syncs repo to/workspaces/{slug}, recalls pinned workspace memory, and locates the fault viaripgrep/ast-grep.code_patch+workspace_exec(Tier 1 · Always Allow) — Creates an automaticGIT_INDEX_FILEcheckpoint, applies the atomic patch, and runs the test suite inside the per-workspacebwrapjail as UID1002(worker) with zero gateway secrets.publish_changes(Tier 3 · Ask Before Running — 1 prompt total) — Shows the scrubbed branch/PR summary. You tap Allow once → PR opens on a non-protected branch (main/masterdirect push blocked).
Why This Exists
Most Remote MCP Servers force an unpleasant tradeoff: either expose dozens of fine-grained tools (triggering endless confirmation popups on every file read or test run) or run an unguarded shell directly on your host.
| Capability | GeminiBastionMCP (v0.3.0) | Generic Proxies (e.g. MetaMCP) | Official Remote MCPs (GitHub / CF) | Local Shell / Stdio MCP |
|---|---|---|---|---|
| Web Gemini, Claude.ai & ChatGPT OAuth 2.1 DCR | Full Support (PKCE S256, DCR up to 16 redirect URIs, 8KB state, RFC 8707/9728) | Often missing RFC 9728/8707 or large state support | Single-vendor hosted only | Desktop/local client only |
| Web & Mobile Approval UX | 10 Tools, 1 Approval Gate (Tier 1/2 Always Allow, only publish_changes asks) | Dozens of fragmented tools = constant confirmation popups | Read & write tools mixed | Confirm every shell command or run wide open |
Multi-Agent Runners + bwrap Sandbox | Built-in (codex, claude_code, gemini_cli, opencode + per-workspace bwrap --unshare-net) | No execution sandbox | API-only; cannot run builds/tests | Runs on host; no background job promotion |
| Secret Isolation & Non-Destructive Undo | Dual-UID (1001/1002) + Optional isolated-runner + SecretScrubber + GIT_INDEX_FILE | Depends on downstream servers | Cloud-managed | Child processes inherit host env |
| Two-Phase Infra & Authenticated Sidecar | stage_mutation_plan (15m TTL + rollback) -> publish_changes + Bearer-auth ops-mcp | Direct passthrough writes | Direct writes | None |
Architecture Overview
flowchart LR
subgraph Clients["Web & Mobile AI Clients"]
G["gemini.google.com\n(Connected Apps)"]
C["Claude.ai / ChatGPT\n/ Cursor / Inspector"]
end
subgraph Edge["Zero-Port Edge Ingress"]
CF["Cloudflare Tunnel\nor TLS Nginx Proxy"]
end
subgraph Gateway["GeminiBastionMCP Gateway (UID 1001: gateway)"]
Portal["GET / Public Portal\n(Zero Private Data)"]
Auth["OAuth 2.1 + PKCE + DCR\nGoogle & GitHub SSO"]
Scrub["SecretScrubber &\nUntrusted Boundary"]
Admin["/admin Mobile PWA\nSSE Live Jobs & Rollback"]
DB[("SQLite WAL (/data)\n0700 gateway-only")]
subgraph Funnel["10-Tool Contract (1 Approval Gate)"]
T1_8["Tier 1 (1-8): Sandbox & Read-Only\nworkspace_manage · code_explore · code_patch\nworkspace_exec · dispatch_runner · job_status\ngithub_inspect · infra_inspect"]
T9["Tier 2 (9): Two-Phase Stage\nstage_mutation_plan (15m TTL + Snapshot)"]
T10["Tier 3 (10): Single External Write Gate\npublish_changes (PR / CF Deploy / Execute Plan)"]
end
end
subgraph Sandbox["Per-Workspace bwrap Jail (UID 1002: worker) or isolated-runner"]
WS["/workspaces/{slug}\nbwrap --tmpfs /workspaces --unshare-net\nGIT_INDEX_FILE Checkpoints · L0/L1/L2"]
Drivers["Multi-Agent Drivers\nCodex · Claude Code · Gemini CLI · OpenCode"]
end
subgraph External["External Targets & Authenticated ops_net"]
GH["GitHub API\n(No push to main/master)"]
CFApi["Cloudflare API\n(Workers / Pages / DNS / KV)"]
MCP2["ops-mcp Bearer Proxy (:9000)\nOPS_MCP_AUTH_TOKEN on ops_net"]
end
Clients -->|"Streamable HTTP /mcp"| CF --> Auth --> Funnel
CF --> Portal & Admin
T1_8 --> WS & Drivers
T1_8 -.->|"Read-Only"| GH & CFApi & MCP2
T9 -->|"Stage Plan + Rollback Snapshot"| DB
T10 -->|"Audited & Scrubbed Writes"| GH & CFApi & MCP2
Admin --> DB & WS
10 Tools, 1 Approval Gate
Instead of exposing 40+ granular tools that bury mobile/web users under approval prompts, GeminiBastionMCP groups capabilities by blast radius so you can configure client permissions cleanly:
Tier 1 — Sandbox Autonomy & Read-Only Inspection (Set to Always Allow)
| # | Tool | Actions & Behavior |
|---|---|---|
| 1 | workspace_manage | list, sync_github, init_cf_ops, list_checkpoints, rollback, memory_list, memory_upsert, memory_delete (auto-recalls persistent workspace memory + detects stack & AGENTS.md / CLAUDE.md) |
| 2 | code_explore | pack (repomix), search (ripgrep), ast (ast-grep), read_lines, read_artifact, git_diff |
| 3 | code_patch | Atomic multi-file patch (hunks + line_hint), create_or_overwrite, delete_file with auto-checkpoint + L0/L1/L2 validation |
| 4 | workspace_exec | Sandboxed shell inside per-workspace bwrap jail (--unshare-net default; opt-in allow_network: true; wait_ms up to 15000; auto-promotes to background SQLite job_id) |
| 5 | dispatch_runner | Background codex_readonly / codex_write / agent_readonly / agent_write / shell_task with pluggable agent_driver (codex, claude_code, gemini_cli, opencode), include_memory (auto-injects workspace memory), thread resume, budgets, and auto-checkpoint |
| 6 | job_status | Poll job status, streamed events, token usage, thread_id, git status -sb, final report, or cancel: true |
| 7 | github_inspect | Read-only PR diffs/files, issue threads, and failed Actions logs (wrapped with untrusted-data boundary markers) |
| 8 | infra_inspect | Read-only Cloudflare inspection (zones, dns_records, workers, pages, kv_namespaces, d1_databases, waf_rules, worker_tail_logs) + downstream MCP-2 readonlyTools |
Tier 2 — Zero-Side-Effect Change Staging (Set to Always Allow)
| # | Tool | Actions & Behavior |
|---|---|---|
| 9 | stage_mutation_plan | Captures pre-change live state to build a rollback_payload and human-readable diff, issuing a 15-minute plan_id for Cloudflare or downstream MCP-2 mutatingTools. Performs zero writes. |
Tier 3 — Single External Write Gate (Set to Ask Before Running)
| # | Tool | Actions & Behavior |
|---|---|---|
| 10 | publish_changes | The ONLY external write exit: github_pr (blocks direct push to main/master/default), github_pr_review, github_comment, cloudflare_worker_deploy (preview URL default), cloudflare_pages_deploy, execute_staged_plan, rollback_plan. |
Pluggable Multi-Agent Drivers
Set a default driver via DEFAULT_AGENT_DRIVER in .env or select one per job with dispatch_runner (runner_type: "agent_readonly" | "agent_write", agent_driver):
Driver (agent_driver) | Engine / CLI | Required Secret (Isolated to Runner Only) | Read-Only vs Write Mode |
|---|---|---|---|
codex (default) | @openai/codex-sdk | OPENAI_API_KEY or CODEX_API_KEY | read-only / workspace-write |
claude_code | claude -p --output-format stream-json | ANTHROPIC_API_KEY | --permission-mode plan / acceptEdits |
gemini_cli | gemini -p ... --output-format stream-json | GEMINI_API_KEY | --approval-mode plan / yolo |
opencode | opencode run --format json | Provider API key(s) | Read-only / write objective execution |
Visual UI Preview
|
Public Gateway Portal ( GET /) — Zero-data-leak status page with one-click /mcp copy, .well-known links & JSON content negotiation.
|
Mobile Operator Cockpit ( /admin PWA) — 4-KPI Pulse Strip, SSE live job streaming, one-click Kill / Rollback confirmations & scrubbed audit trail.
|
1-Minute Quick Start (GHCR Zero-Build)
docker/docker-compose.yml runs gateway with zero host ports exposed (expose: ["8787"] only), pulling pre-built GHCR images in seconds (lite ~350MB by default, or full with Python 3.12 + uv, mise, ruff, biome, pyright, ast-grep, repomix, shellcheck, hadolint, actionlint, gitleaks, gh, wrangler).
Option A: Zero-Build GHCR Pull + Cloudflare Tunnel (Recommended)
-
Pull directly or clone the Compose stack:
docker pull ghcr.io/kaiserunix/gemini-bastion-mcp:lite # Or full workbench image: # docker pull ghcr.io/kaiserunix/gemini-bastion-mcp:full git clone https://github.com/Kaiserunix/gemini-bastion-mcp.git cd gemini-bastion-mcp cp .env.example .env -
Generate
ADMIN_PASSWORD_HASH(scrypt:) andOAUTH_SIGNING_SECRET: Supported formats in production arescrypt:<saltHex>:<keyHex>(recommended, Docker-Compose-safe without$escaping) andsha256:<hex>(legacyscrypt$<saltHex>$<keyHex>/sha256$<hex>are also supported; escape$as$$in Docker Compose.env):node -e 'const c=require("node:crypto"),s=c.randomBytes(16).toString("hex");console.log(`scrypt:${s}:${c.scryptSync(process.argv[1],s,32,{N:16384,r:8,p:1}).toString("hex")}`)' 'your-admin-password'node -e 'console.log(require("node:crypto").randomBytes(32).toString("hex"))' -
Set core values in
.env, point your Cloudflare Tunnel Public Hostname (mcp.yourdomain.com) tohttp://gateway:8787, putCLOUDFLARE_TUNNEL_TOKEN=<token>indocker/.env(or export it in your shell), and start in 30 seconds:docker compose -f docker/docker-compose.yml pull docker compose -f docker/docker-compose.yml up -dTo switch to the
:fulltoolchain image, setBASTION_IMAGE_TAG=fullindocker/.env(or build locally withBASTION_TARGET=runtime-full docker compose -f docker/docker-compose.yml up -d --build).
[!IMPORTANT] Node 22 Security Baseline: Both
runtime-liteandruntime-fullindocker/DockerfileenforceNode >= 22.23.4at build time.cloudflaredreceives onlyTUNNEL_TOKEN(never mounts../.env).
Environment Variable Reference (.env)
| Variable | Purpose |
|---|---|
PUBLIC_DOMAIN | Exact HTTPS origin of your gateway (e.g. https://mcp.yourdomain.com) |
TRUST_CF_CONNECTING_IP | true behind Cloudflare Tunnel/CDN; false behind standalone Nginx |
OAUTH_SIGNING_SECRET | >= 32-character random hex/base64 secret (NODE_ENV=production rejects placeholders) |
ADMIN_PASSWORD_HASH | scrypt:<saltHex>:<keyHex> (recommended) or sha256:<hex> |
OAUTH_STATIC_CLIENT_ID / _SECRET | Optional static OAuth client credentials (fallback for non-DCR clients) |
GOOGLE_OAUTH_* / GITHUB_OAUTH_* | Optional fail-closed upstream operator SSO credentials + allowlists |
SANDBOX_BWRAP_ISOLATION | Enable per-workspace bwrap FS & --unshare-net jail (default true on Linux) |
SANDBOX_STRICT_ISOLATION | Fail closed if bwrap cannot create namespaces (default false) |
DEFAULT_AGENT_DRIVER | Default runner driver: codex (default), claude_code, gemini_cli, opencode |
AGENT_RUNNER_URL / _AUTH_TOKEN | Optional dedicated isolated-runner sidecar URL + Bearer secret (>= 24 chars) |
OPS_MCP_AUTH_TOKEN | Bearer token (>= 24 chars) protecting ops-mcp sidecar |
GH_TOKEN | GitHub PAT (gateway-only; never exposed to workspace_exec or agents) |
CLOUDFLARE_ACCOUNT_ID / _READONLY_API_TOKEN / _API_TOKEN | Cloudflare account + split read-only vs write tokens |
OPENAI_API_KEY / CODEX_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY | Agent driver API credentials |
NOTIFY_WEBHOOK_URL | Optional webhook endpoint for scrubbed job & plan alerts |
WATCHDOG_ENABLED / GITHUB_WEBHOOK_SECRET | Optional read-only GitHub CI Watchdog (POST /webhooks/github, fail-closed HMAC-SHA256) |
WATCHDOG_ALLOWED_REPOS / WATCHDOG_AGENT_DRIVER | Comma-separated owner/repo allowlist and optional readonly driver override |
DOWNSTREAM_MCPS_FILE / _JSON | Optional downstream MCP-2 federation registry |
Option B: Reverse Proxy with Nginx (Loopback Host Port)
Bind gateway strictly to loopback (127.0.0.1:8787:8787 or 127.0.0.1:39120:8787) via a docker-compose.override.yml, set TRUST_CF_CONNECTING_IP=false in .env, and run gateway without cloudflared:
docker compose -f docker/docker-compose.yml up -d gateway
Nginx Reverse Proxy Config (Streamable HTTP, SSE & 8KB OAuth State)
server {
listen 443 ssl http2;
server_name mcp.yourdomain.com;
# Required so Gemini's 2400-8192 byte OAuth state query string never hits 414 Request-URI Too Large
large_client_header_buffers 4 16k;
client_max_body_size 1m;
location / {
proxy_pass http://127.0.0.1:8787;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_request_buffering off;
proxy_read_timeout 300s;
}
}
Option C: Local Development
npm install
cp .env.example .env
# Set DATA_DIR=./.local/data, WORKSPACES_DIR=./.local/workspaces, OAUTH_SIGNING_SECRET, and ADMIN_PASSWORD_HASH
npm run typecheck
npm test
npm run dev
Verify at http://127.0.0.1:8787/healthz and http://127.0.0.1:8787/. Both npm run dev and npm start automatically load .env via Node's --env-file-if-exists=.env.
Connecting AI Clients
GeminiBastionMCP implements MCP 2025-11-25 Streamable HTTP (stateless /mcp, zero legacy HTTP+SSE) with OAuth 2.1 + PKCE (S256) + RFC 8707 Resource Indicators + RFC 9728 Protected Resource Metadata.
- Web Gemini (
gemini.google.comConnected Apps):- Confirm
PUBLIC_DOMAINmatches your public HTTPS URL andOAUTH_ALLOWED_REDIRECT_HOSTSincludesgemini.google.com,aistudio.google.com,accounts.google.com(default in.env.example). - Add
https://mcp.yourdomain.com/mcpin Gemini Connected Apps / Custom MCP connector settings. - Gemini automatically discovers
/.well-known/oauth-protected-resource,/.well-known/oauth-authorization-server, and registers viaPOST /oauth/register(up to 16 redirect URIs per client andstateup to 8192 bytes).
- Confirm
- Claude.ai Custom Connectors, ChatGPT MCP & MCP Inspector:
- Automatic DCR: Point directly to
https://mcp.yourdomain.com/mcp. - Static Client Fallback: Set
OAUTH_STATIC_CLIENT_IDandOAUTH_STATIC_CLIENT_SECRETin.env, restartgateway, and point Authorization URL to/oauth/authorizeand Token URL to/oauth/token.
- Automatic DCR: Point directly to
Upstream Operator Login (Google & GitHub OAuth)
In addition to ADMIN_PASSWORD_HASH, you can enable Google OAuth and/or GitHub OAuth SSO for one-tap operator sign-in on /admin/login and MCP consent approval on /oauth/authorize:
- Register Callback URLs:
- Google Cloud Console (OAuth 2.0 Web Application):
https://<PUBLIC_DOMAIN>/auth/idp/google/callback - GitHub Developer Settings (OAuth App):
https://<PUBLIC_DOMAIN>/auth/idp/github/callback
- Google Cloud Console (OAuth 2.0 Web Application):
- Set
.envCredentials & Allowlists:- Google:
GOOGLE_OAUTH_CLIENT_ID,GOOGLE_OAUTH_CLIENT_SECRET,GOOGLE_OAUTH_ALLOWED_EMAILS - GitHub:
GITHUB_OAUTH_CLIENT_ID,GITHUB_OAUTH_CLIENT_SECRET,GITHUB_OAUTH_ALLOWED_USERS, optionalGITHUB_OAUTH_ALLOWED_IDS(when both users & IDs are set, both must match)
- Google:
[!IMPORTANT] Fail-Closed Single-Operator Security: Both IdPs stay disabled unless credentials and a non-empty allowlist are configured — and in
NODE_ENV=production, providing client credentials without an allowlist fails startup closed. Google requiresemail_verified: true, and all upstream flows enforce PKCES256,HttpOnlybinding cookies, and CSRF validation.
Security Architecture v2 (6-Layer Defense-in-Depth)
- Per-Workspace
bwrapFS & Network Jail: On Linux (SANDBOX_BWRAP_ISOLATION=true),workspace_execand CLI agent drivers execute insidebubblewrap(--ro-bind / / --tmpfs /workspaces --bind <workspaceDir> --tmpfs /data --unshare-net) so sibling workspaces are invisible and network egress is disabled unless explicitly opted in (allow_network: true). SetSANDBOX_STRICT_ISOLATION=trueto fail closed ifbwrapnamespaces are unavailable. - Zero Gateway Secret Leakage &
SecretScrubber:buildSandboxedEnv()stripsGH_TOKEN,CLOUDFLARE_*,OAUTH_SIGNING_SECRET,ADMIN_PASSWORD_HASH,NOTIFY_WEBHOOK_URL,OPS_MCP_AUTH_TOKEN,AGENT_RUNNER_AUTH_TOKEN, and unused LLM keys. All outputs, artifacts, and webhooks pass throughSecretScrubber. - Linux UID 1001 / 1002 Isolation + Optional
isolated-runnerSidecar:gateway(UID1001) owns/data(0700, SQLite DB,/data/artifacts,/data/codex), whileworker(UID1002) owns/workspaces. Enable--profile isolated-runner(AGENT_RUNNER_URL=http://isolated-runner:8788,AGENT_RUNNER_AUTH_TOKEN >= 24 chars) to run autonomous coding agents in a separate UID1002container with no/data, no SQLite, and no GH/CF/OAuth secrets. - Authenticated
ops-mcpBearer Proxy:docker/ops-mcp-auth-proxy.mjswrapsops-mcpon port9000, fails closed unlessOPS_MCP_AUTH_TOKEN >= 24chars is set, and validatesAuthorization: Bearerwithcrypto.timingSafeEqual.DownstreamMcpBridgeinjects per-request tokens viaauthTokenEnv. - Non-Destructive Git Checkpoints & Protected Branch Guard: Pre-patch and pre-agent snapshots use a temporary
GIT_INDEX_FILE(refs/mcp-checkpoints/*).publish_changesblocks direct pushes tomain/master/default and blocks sensitive files (.env*,*.pem,*.key,id_rsa*,.dev.vars*). - OAuth 2.1 Family Rotation & Untrusted Boundary: Refresh token reuse outside the 60s grace window revokes the entire family; external GitHub/Cloudflare/MCP-2 data is wrapped as untrusted content.
[!NOTE] Data Privacy & Platform Policy Note:
GeminiBastionMCPuses official Custom Connected Apps / MCP Streamable HTTP + OAuth 2.1 protocols only (never browser automation, scraping, or cookie-hijacking against consumer web apps). Tool outputs returned to consumer web AI chats are processed under that AI provider's activity and privacy policy — avoid connecting regulated PII or strictly confidential corporate repositories to personal consumer accounts, and keep the built-in sensitive-file blacklist andSecretScrubberenabled.
Running Optional Sidecars (--profile isolated-runner, --profile ops & Webhooks)
- Dedicated
isolated-runnerSidecar: SetAGENT_RUNNER_URL=http://isolated-runner:8788andAGENT_RUNNER_AUTH_TOKEN=<24+ char random token>in.env(and export or putAGENT_RUNNER_AUTH_TOKENindocker/.env):docker compose -f docker/docker-compose.yml --profile isolated-runner up -d - Authenticated
ops-mcpSidecar (OPS_MCP_AUTH_TOKEN): Createdocker/ops-ssh/with your restrictedconfig.json& SSH key, copydocker/ops-mcp-config.example.jsontodocker/ops-mcp-config.json(url: "http://ops-mcp:9000/mcp",authTokenEnv: "OPS_MCP_AUTH_TOKEN"), uncomment the volume mount indocker/docker-compose.yml, setOPS_MCP_AUTH_TOKEN(>= 24chars) +DOWNSTREAM_MCPS_FILE=/etc/gemini-bastion/ops-mcp-config.json, and launch:docker compose -f docker/docker-compose.yml --profile ops up -d - Webhook Notifications: Set
NOTIFY_WEBHOOK_URLin.envfor scrubbed JSON POST alerts on job completion/failure or staged plan execution/rollback.
Gemini Gem Prompt, Persistent Memory & MCP Prompts
- Ready-to-Paste Gem / Claude Project System Prompt: Use
docs/GEMINI_GEM_PROMPT.md(English & 简体中文) when creating a dedicated Gemini Gem (gemini.google.com/gems), Claude Project, or ChatGPT Custom GPT so the model follows the 10-tool SOP automatically. - MCP
instructions& 4 Built-In Prompts:McpServerships conciseinstructionsoninitializeplus 4 official MCP Prompts (review_pr,fix_issue,resume_workspace_task,ops_health_check). - Cross-Session Persistent Workspace Memory (
workspace_memories):- Store durable
task_state,decision,pitfall,preference, andnoteentries viaworkspace_manage(memory_list,memory_upsert,memory_delete— secret-scanned before saving, up to 100 entries / 8KB per entry). workspace_manage(list,sync_github,init_cf_ops) automatically recalls pinned/recent memories,dispatch_runner(include_memory: true) injects[Workspace Persistent Memory]into background agents, and/adminincludes a Memory tab to inspect or delete entries.
- Store durable
Optional Read-Only GitHub CI Watchdog
Enable WATCHDOG_ENABLED=true with GITHUB_WEBHOOK_SECRET (>= 24 chars) and WATCHDOG_ALLOWED_REPOS=owner/repo to point GitHub workflow_run webhooks at https://<PUBLIC_DOMAIN>/webhooks/github:
- Requests are rate-limited, capped at 64KB (
413), HMAC-SHA256 verified (X-Hub-Signature-256->401on mismatch), and restricted toWATCHDOG_ALLOWED_REPOS(403otherwise). - When a workflow fails (
action: "completed",conclusion: "failure"), the Watchdog dispatches a strictlyreadonlydiagnostic job, saves a pinnedci-failure-<runId>task_statememory, and sends a scrubbedNOTIFY_WEBHOOK_URLalert so you can open Web Gemini and take over immediately. - 100% Policy-Compliant: Never writes repo code, never calls
publish_changes, and never automates any consumer web UI.
Official MCP Registry & GHCR Images
- Official MCP Registry:
server.json(io.github.Kaiserunix/gemini-bastion-mcp, schema2025-12-11, validated viamcp-publisher). - Automated OIDC Publishing (
github-oidc): Taggingv*triggers.github/workflows/docker-publish.ymlto push GHCR images first and then runpublish-mcp-registry(mcp-publisher validate->mcp-publisher login github-oidc->mcp-publisher publish server.json). - GHCR Images:
ghcr.io/kaiserunix/gemini-bastion-mcp:lite/:latest/:<version>-lite(~350MB slim gateway +bwrap+git+ripgrep)ghcr.io/kaiserunix/gemini-bastion-mcp:full/:<version>-full(adds Python 3.12 +uv,mise,ruff,pyright,biome,ast-grep,repomix,shellcheck,hadolint,actionlint,gitleaks,gh,wrangler)ghcr.io/kaiserunix/gemini-bastion-mcp-ops:latest/:<version>(authenticatedops-mcpBearer proxy sidecar)
Feedback, Issues & Contributions Welcome
[!TIP] Have a bug report, new agent driver idea, or client OAuth quirk (Gemini / Claude / ChatGPT)? Please open a GitHub Issue, submit a PR, or start a thread in GitHub Discussions — community feedback directly shapes our next release!
- Documentation Hub: Documentation Index (
docs/INDEX.md) · Architecture (DESIGN.md) · Gemini Gem Prompt (docs/GEMINI_GEM_PROMPT.md) · Product Strategy (docs/PRODUCT_STRATEGY.md) · UX Design Spec (docs/UX_EXPERIENCE_AND_DESIGN_SPEC.md) - Roadmap: Per-job ephemeral container/microVM worker isolation (
v0.3) and multi-operator RBAC policies. - Contributing: See CONTRIBUTING.md for local setup, architectural guardrails, and PR checklist.
- Security Policy: See SECURITY.md for threat model and private vulnerability reporting.
- Release History & License: CHANGELOG.md · MIT License
ghcr.io/kaiserunix/gemini-bastion-mcp:0.3.0-litedocker pull ghcr.io/kaiserunix/gemini-bastion-mcp:0.3.0-lite:undefinedghcr.io/kaiserunix/gemini-bastion-mcp:0.3.0-fulldocker pull ghcr.io/kaiserunix/gemini-bastion-mcp:0.3.0-full:undefined