GitSeed – Self-hosted control plane for AI coding agents

GitSeed

Your SDLC, run by agents, governed by you.

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

Quickstart

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
      

First 60 Seconds in the UI

• Sign in at http://localhost:8421 using the [email protected] credentials printed by ./scripts/init.sh (or set GITSEED_ADMIN_PASSWORD in .env beforehand).

• Connect a Model & Repo (1-Click Wizard): Pick an API key (Anthropic, OpenAI, Gemini, xAI), local Ollama / vLLM, or single-user Personal 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 a Local Folder on disk.

• Pick an API key (Anthropic, OpenAI, Gemini, xAI), local Ollama / vLLM, or single-user Personal 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 a Local Folder on disk.

• Plant Your First Seed: Create a project and submit a prompt (full 5-stage pipeline, ⚡ Fast-Track straight to code, or 2–3 parallel model opinions), or click + New ▾ to open a live Coding Agent chat, Browser PTY terminal, or embedded VS Code Web session.

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
      

Why GitSeed?

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-hardened egress-proxy; a separate read-only finalize container enforces blocked_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 via gitseed receipt verify.

• Parallel 3-Model "Second Opinions": Dispatch up to 3 agents in parallel during Ideate, Plan, or Review 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 via LiteLLM (cloud APIs or local Ollama / vLLM / LM Studio), or sign in with your personal Claude Pro/Max, ChatGPT Plus/Pro, or Gemini subscription inside an isolated container.

• Autonomous Pipelines + Live Sandbox Rescue: Drop into any workspace from the persistent SessionDock (persistent browser PTY terminal, Monaco, and isolated VS 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 across Ideate → 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-remote Local Folder.

How GitSeed Compares

How It Works: The 5-Stage SDLC

        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.

Frontier Models, Personal Mode & Local Open-Weight LLMs

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:

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.

Broker-Enforced Security & Signed Governance Receipts

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

• 3-Phase Container Split (prepare → agent → finalize): The agent container runs with CapDrop: ALL, no-new-privileges, non-root UID 1000, no Docker socket, and zero Git credentials. All repository commits, blocked_paths checks, and secret scans on added lines happen inside the separate finalize 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 restricted docker-socket-proxy (never mounting raw /var/run/docker.sock into api or scheduler), and runner containers reach external APIs only through an SSRF-hardened egress-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

        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.

Developer CLI (gitseed)

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

        # Authenticate against your control plane
gitseed login http://localhost:8420

# Inspect projects, seeds, runs, and governance policies
gitseed get projects
gitseed get seeds -p my-project
gitseed describe seed my-project#1

# Create or sync seeds from declarative Markdown manifests (or Fast-Track straight to Execute)
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/

# Stream live container logs, inspect diffs, and steer, fast-track, or approve stages
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"

# Fetch and cryptographically verify a Seed's Ed25519-signed Governance Receipt (online or offline)
gitseed receipt get my-project#1 -f receipt.json
gitseed receipt verify receipt.json --public-key-file pubkey.pem

# Spin up an interactive sandbox or live coding agent session
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"

# Ask @coordinator to triage blocked seeds or summarize spend
gitseed ask "Which seeds are awaiting review and what is our spend this week?"

# Launch the interactive split-pane Terminal UI (k9s / lazygit style)
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.

MCP Server (gitseed-mcp)

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:

        # stdio transport (local CLI binary)
claude mcp add gitseed \
  -e GITSEED_API_URL=http://localhost:8420 \
  -e GITSEED_TOKEN=gsp_your_pat_token \
  -- gitseed-mcp

# Or connect to the running Docker Compose loopback HTTP endpoint:
# URL: http://127.0.0.1:8422/mcp (Header: Authorization: Bearer gsp_...)
      

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.

Webhooks, Self-Healing CI & Local Folder Auto-Sync

• Inbound GitHub, GitLab & Bitbucket Webhooks (services/webhooks.py): Issue-to-Seed Trigger: Labeling or opening an issue with the configured trigger label (default gitseed) 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 to Execute to fix the build.

• Issue-to-Seed Trigger: Labeling or opening an issue with the configured trigger label (default gitseed) 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 to Execute 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 sanitized post-receive hook that auto-stashes uncommitted local IDE changes, fast-forwards your working tree when a Seed merges, and restores your stash.

• 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 sanitized post-receive hook that auto-stashes uncommitted local IDE changes, fast-forwards your working tree when a Seed merges, and restores your stash.

Architecture & Monorepo Layout

        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.

Single-Image Entrypoint Modes & Local Development

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):

        # 1. Install all Python & Web workspace dependencies
uv sync --all-packages
pnpm --filter web install

# 2. Run Python tests, linting & typechecking
uv run python -m pytest
uv run ruff check .
uv run mypy packages/common apps/core apps/cli apps/mcp apps/runner

# 3. Run Web UI lint, unit tests & production build
pnpm --filter web lint
pnpm --filter web test
pnpm --filter web build
      

License & Trademarks

• License: Copyright 2026 Trent Seed. The GitSeed Control Plane, Runner, Web UI, CLI/TUI, MCP Server, Shared Schemas, and Helm Chart in this repository are 100% open source under the Apache License, Version 2.0 (see NOTICE), 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. See TRADEMARKS.md for what's allowed.

• Privacy: Self-hosted GitSeed sends zero telemetry; your code, prompts, and credentials stay on your infrastructure. See PRIVACY.md.

• Contributions: External pull requests require accepting the GitSeed Contributor License Agreement (one PR comment, handled by a bot). See CONTRIBUTING.md and the Code 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 unless INCLUDE_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.