GitSeed – Self-hosted control plane for AI coding agents

Self-hosted, vendor-neutral control plane for AI software engineering. Run Claude Code, Codex, Gemini, OpenCode, and more inside isolated 3-phase containers (prepare → agent → finalize) on your own infrastructure, complete with Ed25519-signed PR Governance Receipts, parallel 3-model Second Opinions, and live docked sandbox rescue.

Quickstart · ** Why GitSeed?** · ** How It Works** · ** Models & Personal Mode** · ** Security & Receipts** · ** CLI & TUI** · ** MCP Server** · ** Architecture** · Concepts

GitSeed-Demo-GitHub.mp4 #

Up and running locally in under 5 minutes with Docker (no cloud account or external Git host required):

git clone https://github.com/gitseed-dev/gitseed.git && cd gitseed
./scripts/init.sh             # generates .env secrets & prints your initial admin login (Windows: .\scripts\init.ps1)
docker compose up -d --build  # starts Web UI (:8421), API (:8420), MCP (:8422), LiteLLM & Postgres

1. Sign in at http://localhost:8421 using the admin@gitseed.local credentials printed by./scripts/init.sh (or setGITSEED_ADMIN_PASSWORD in.env beforehand).
2. Connect a Model & Repo (1-Click Wizard) :

• Pick an API key (Anthropic, OpenAI, Gemini, xAI), local Ollama / vLLM , or single-userPersonal Mode CLI OAuth (Claude Code ,Codex ,Gemini ,Antigravity ,Grok ). This automatically provisions all 5 stage agents (@ideator ,@planner ,@coder ,@reviewer ,@merger ) plus@coordinator .
• Connect Git via 1-Click GitHub App , GitLab/Bitbucket token, or point directly at aLocal Folder on disk.

3. Pick an API key (Anthropic, OpenAI, Gemini, xAI), local
4. Plant Your First Seed : Create a project and submit a prompt (full 5-stage pipeline,⚡ Fast-Track straight to code, or2–3 parallel model opinions ), or click**+ New ▾** to open a live Coding Agent chat, Browser PTY terminal, or embedded VS Code Web session.

Kubernetes (Helm) Deployment & Service Port Map #

Deploy to Kubernetes from the included Helm chart after pushing images to your cluster registry (see charts/gitseed/README.md):

helm upgrade --install gitseed ./charts/gitseed \
  --namespace gitseed \
  --create-namespace \
  --set image.repository=ghcr.io/gitseed-dev/gitseed \
  --set runnerImage.repository=ghcr.io/gitseed-dev/runner

Ad-hoc coding prompts work for single files, but shipping production software with agents requires isolated execution, untrusted-agent containment, review gates, provenance, and spend controls:

• Untrusted Agent, Trusted Broker (prepare → agent → finalize) : Coding agents run with zero Git credentials behind an SSRF-hardenedegress-proxy ; a separate read-onlyfinalize container enforcesblocked_paths and added-line secret scanning before pushing.
• Ed25519-Signed PR Governance Receipts : Every Pull Request receives a cryptographically signed receipt (gitseed.receipt.v1 ) attesting to the locked spec, models, spend mode, security scans, and human approvals, verifiable offline viagitseed receipt verify .
• Parallel 3-Model "Second Opinions" : Dispatch up to3 agents in parallel duringIdeate ,Plan , orReview to compare competing specs, task plans, or code reviews side-by-side before approving.
• Cloud BYOK, Local GPUs & Single-User "Personal Mode" : Enforce hard per-run USD caps viaLiteLLM (cloud APIs or localOllama / vLLM / LM Studio ), or sign in with your personalClaude Pro/Max ,ChatGPT Plus/Pro , orGemini subscription inside an isolated container.
• Autonomous Pipelines + Live Sandbox Rescue : Drop into any workspace from the persistent**SessionDock** (persistent browser PTY terminal, Monaco, and isolatedVS Code Web ), leave inline diff comments, or@coder -steer an active run without losing progress.
• 5-Stage SDLC or ⚡ Fast-Track + Self-Healing CI : Lock specs acrossIdeate → Plan → Execute → Review → Merge for complex features,⚡ Fast-Track (Execute → Review → Merge ) for quick fixes, auto-remediate failing PR CI checks, or sync against a zero-remoteLocal Folder .

flowchart LR
    I["1. Ideate<br/>@ideator"] --> P["2. Plan<br/>@planner"]
    P --> E["3. Execute<br/>@coder"]
    E --> R["4. Review<br/>@reviewer"]
    R --> M["5. Merge<br/>@merger"]

Need to ship a straightforward bugfix? Toggle ⚡ Fast-Track to jump straight into Execute → Review → Merge while keeping clean-room finalize checks, signed Governance Receipts, and review gates intact. Read docs/concepts.md for a concise tour of Project, Seed, Run, Policy, and Agent.

Every stage agent (@ideator, @planner, @coder, @reviewer, @merger, @coordinator, or custom agents) can be independently bound to a different CLI runtime and model backend, with transparent labeling of enforced vs. estimated spend controls:

Important

Personal Mode (cli_oauth) is strictly single-user and owner-bound. Consumer subscriptions (Claude Pro/Max, ChatGPT Plus/Pro, personal Google accounts) are licensed to one individual. GitSeed binds each Personal Mode backend to owner_user_id so other users cannot attach, run, or inspect it, and administrators can disable Personal Mode instance-wide with GITSEED_ALLOW_PERSONAL_CLI_OAUTH=false. For shared team projects or scheduled CI pipelines, use API keys via LiteLLM or local open-weight models.

Runtime availability: opencode, claude-code, codex, antigravity (agy), and gemini are pre-installed out of the box when building gitseed/runner locally (docker compose up -d --build, where INCLUDE_PROPRIETARY_CLIS=true by default; pass --build-arg INCLUDE_PROPRIETARY_CLIS=false when building strictly FOSS-only or redistributed images). grok-build (grok) ships with a built-in runtime adapter in gitseed_runner ready for custom layered binaries or GROK_CLI_INSTALL_URL image builds. See apps/runner/README.md.

GitSeed is architected around the principle that coding agents are untrusted (SECURITY.md):

• 3-Phase Container Split (prepare → agent → finalize) : The agent container runs withCapDrop: ALL ,no-new-privileges , non-root UID1000 , no Docker socket, and zero Git credentials. All repository commits,blocked_paths checks, and secret scans on added lines happen inside the separatefinalize container, which mounts/workspace read-only (:ro ) and commits via a clean.git directory outside the workspace.
• Socket & Egress Proxies : Control-plane services communicate with Docker through a restricteddocker-socket-proxy (never mounting raw/var/run/docker.sock intoapi orscheduler ), and runner containers reach external APIs only through an SSRF-hardenedegress-proxy that blocks RFC1918 private networks, loopback, and cloud metadata (169.254.169.254 ) after DNS resolution.
• Ed25519 Governance Receipts (gitseed.receipt.v1) : Verify any Seed's provenance directly from the CLI (online or completely offline against a pinned PEM key):

gitseed receipt get my-project#1 -f receipt.json
gitseed receipt verify receipt.json --public-key-file pubkey.pem

See SECURITY.md for the complete Threat Model, Enforced vs. Estimated Controls table, Known Residual Risks, and the test_evil_agent_redteam.py adversarial verification suite.

Install the CLI & interactive TUI (gitseed tui) via uv or pip (or invoke via docker compose exec api gitseed):

gitseed login http://localhost:8420

gitseed get projects
gitseed get seeds -p my-project
gitseed describe seed my-project#1

gitseed create seed -f seed.md
gitseed create seed "Fix OAuth callback timeout" -p my-project --summary "Increase timeout to 15s" --fast-track
gitseed apply -f .gitseed/manifests/

gitseed logs my-project#1 -f
gitseed diff my-project#1
gitseed steer my-project#1 "Also add rate-limit headers to the response" -a @coder
gitseed advance my-project#1 --fast-track
gitseed approve my-project#1 -m "LGTM, spec and task plan look solid"

gitseed receipt get my-project#1 -f receipt.json
gitseed receipt verify receipt.json --public-key-file pubkey.pem

gitseed sandbox start -p my-project --seed my-project#1 -c "pytest -q"
gitseed session start -p my-project --agent @coder -m "Investigate flaky auth test"

gitseed ask "Which seeds are awaiting review and what is our spend this week?"

gitseed tui

All inspection commands support -o table (default), -o wide, -o json, and -o md (GitHub-Flavored Markdown for CI summaries). See apps/cli/README.md for the complete command reference.

Connect Claude Code, Cursor, Windsurf, or Antigravity directly to GitSeed so your IDE agent can inspect seeds, read run logs, manage live agent sessions, and approve stage gates:

claude mcp add gitseed \
  -e GITSEED_API_URL=http://localhost:8420 \
  -e GITSEED_TOKEN=gsp_your_pat_token \
  -- gitseed-mcp

Every MCP tool includes explicit ToolAnnotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), plus optional --toolsets and --read-only scoping so MCP clients can automatically allow read-only queries while prompting before state mutations. See apps/mcp/README.md for all 65 available MCP tools, resources, and prompts.

• Inbound GitHub, GitLab & Bitbucket Webhooks (services/webhooks.py) :
  • Issue-to-Seed Trigger : Labeling or opening an issue with the configured trigger label (defaultgitseed ) automatically creates and queues a Seed linked back to the source issue.
  • PR Comment Steering : Commenting@coder ,@planner , or@reviewer on a GitHub Pull Request or GitLab Merge Request syncs the comment into the Seed timeline and either steers the active container run in place or queues a remediation pass.
  • Self-Healing CI Remediation : When a GitHub Actions workflow or GitLab CI pipeline fails on a Seed branch (check_run /workflow_run /pipeline ), GitSeed automatically creates a remediation task with the failure details and dispatches@coder back toExecute to fix the build.
• Zero-Remote Local Folder Git Sync (services/local_git.py) :
  • Create projects backed by a local directory on disk with no GitHub, GitLab, or Bitbucket account required.
  • GitSeed manages a refname-hardened bare Git repository exposed over internal Git Smart HTTP (/api/v1/local-git/<slug>.git ) for container runners and installs a sanitizedpost-receive hook that auto-stashes uncommitted local IDE changes, fast-forwards your working tree when a Seed merges, and restores your stash.

flowchart TB
    subgraph Surfaces["Operator & IDE Surfaces"]
        Web["apps/web<br/>React 19 Control Plane UI (:8421)"]
        CLI["apps/cli<br/>gitseed Terminal CLI & TUI"]
        MCP["apps/mcp<br/>65-Tool MCP Server (:8422)"]
    end

    subgraph ControlPlane["GitSeed Control Plane (apps/core)"]
        API["FastAPI REST, SSE, Receipts & PTY Server (:8420)"]
        Sched["Background Scheduler & 3-Phase Reconciler"]
        Common["packages/common<br/>Shared Pydantic v2 Schemas & Receipt Contracts"]
    end

    subgraph Infra["State, Proxies & Model Routing"]
        PG[("PostgreSQL 16")]
        DF[("Valkey / Redis")]
        LLM["LiteLLM Proxy (:4000)"]
        SockProxy["docker-socket-proxy"]
        EgressProxy["egress-proxy (DNS/IP Guard)"]
    end

    subgraph Compute["Isolated Compute (apps/runner on gitseed-runners)"]
        Prep["1. prepare Container<br/>(Trusted Clone & Hook Strip)"]
        Agent["2. agent Container<br/>(Untrusted CLI Sandbox)"]
        Fin["3. finalize Container<br/>(:ro Mount · Blocked Paths · Secret Scan · Push)"]
        Sandbox["Interactive Sandbox & Live Agent Session"]
    end

    Web & CLI & MCP --> API
    API & Sched --> PG & DF & LLM
    Sched -->|Container API via| SockProxy
    SockProxy -->|Spawns| Prep --> Agent --> Fin
    API -->|Manages PTY / VS Code / Turns via| SockProxy --> Sandbox
    Agent & Sandbox -->|Filtered Egress| EgressProxy
    Prep & Fin -->|Single-Use Broker Tokens| API
    Agent -->|Scoped Agent Token + Model Calls| API & LLM

See docs/architecture.md and docs/concepts.md for deeper architectural documentation.

The root Dockerfile packages the entire control plane into gitseed/gitseed, selectable via container command ( api | web | scheduler | egress-proxy | mcp | cli | migrate | help):

docker build -t gitseed/gitseed:dev .
docker build -t gitseed/runner:dev ./apps/runner
docker run --rm gitseed/gitseed:dev help

For local workspace development (Python 3.12+ with uv and Node.js 22+ with pnpm):

uv sync --all-packages
pnpm --filter web install

uv run python -m pytest
uv run ruff check .
uv run mypy packages/common apps/core apps/cli apps/mcp apps/runner

pnpm --filter web lint
pnpm --filter web test
pnpm --filter web build

• License : Copyright 2026 Trent Seed. TheGitSeed Control Plane, Runner, Web UI, CLI/TUI, MCP Server, Shared Schemas, and Helm Chart in this repository are 100% open source under theApache License, Version 2.0 (seeNOTICE ), free to self-host, modify, and deploy for personal or commercial use.
• Trademarks : "GitSeed" and the GitSeed logo are trademarks of Trent Seed. The Apache License, Version 2.0 does not grant permission to use the GitSeed name, brand, or logo for derivative products or hosted services. SeeTRADEMARKS.md for what's allowed.
• Privacy : Self-hosted GitSeed sends zero telemetry; your code, prompts, and credentials stay on your infrastructure. SeePRIVACY.md .
• Contributions : External pull requests require accepting theGitSeed Contributor License Agreement (one PR comment, handled by a bot). SeeCONTRIBUTING.md and theCode of Conduct .
• Third-party agent CLIs & model providers : GitSeed orchestrates third-party tools (e.g., Claude Code, Codex, Gemini CLI) and model APIs that have their own licenses and terms of service. Claude Code is proprietary (installed locally at image build time unlessINCLUDE_PROPRIETARY_CLIS=false ) and is not part of GitSeed's Apache-2.0 source distribution; redistributed container images must omit proprietary vendor CLIs. You are responsible for complying with each provider's terms, including any restrictions on using consumer subscriptions with third-party tools.