This page is the map of the machinery. It shows what each part is, which repo holds it, and how a labeled issue becomes a running app. Go deeper in Platform Internals and Security Model.

The one diagram

flowchart LR
    subgraph forgejo["Forgejo — git.open-platform.sh (control plane)"]
        I[Issues / PRs]
        P[Packages: OCI images + charts]
        A[Actions CI]
    end
    D["Dispatcher (open-platform/agents)\nwebhooks + 60s sweep"]
    M["MCP (open-platform/mcp)\nmcp.open-platform.sh"]
    G["open-platform/gitops repo"]
    F[Flux]
    subgraph cluster["Cluster"]
        PL[Platform components]
        APPS["Apps: one namespace per env"]
    end
    CI["Isolated CI pool\nruns-on: isolated"]
    R["Node registry mirror\n127.0.0.1:31100"]
    GR["Grafana + Prometheus\ngrafana.open-platform.sh"]

    I -- "webhook: POST /hook" --> D
    D -- "spawns agent runs,\nposts PRs/comments" --> I
    D -- "tool calls" --> M
    M -- "commits overlays" --> G
    G -- "converges (1m)" --> F
    F --> PL
    F --> APPS
    A --> CI
    CI -- "buildctl push image + chart" --> P
    P -- "OCIRepository pull" --> F
    R --> cluster
    D -- "/metrics" --> GR
    M -- "/metrics" --> GR
    GR -- "/flow-api overrides" --> D

Control plane: Forgejo

Forgejo at https://git.open-platform.sh is not one component among many — it is the platform's interface. Repos, issues, PRs, labels, milestones, Actions runs, and the package registry are the whole state surface. Every state change is a git commit or a Forgejo API event. So every change is auditable, diffable, and observable through webhooks. The platform generates apps from open-platform/app-template. Each app's container image and Helm chart live in Forgejo's own OCI package registry, under the owning org.

The plat user is the platform admin — the root. It is the site admin of Forgejo and the Owner of the platform's own org, open-platform, which holds the system repos (open-platform/gitops, open-platform/mcp, open-platform/agents, open-platform/app-template, open-platform/ci-runner, open-platform/mitosis) and the front door (open-platform/www). Its admin credential powers the dispatcher and MCP internally. That credential never reaches an agent run. Each run gets per-repo deploy keys and scoped tokens. Tenant CI gets a per-org REGISTRY_TOKEN that carries write:package only.

Brain: the dispatcher (open-platform/agents)

One daemon turns Forgejo into an autonomous software factory. It listens for Forgejo webhooks on POST /hook. It also runs a full reconciliation sweep every 60 seconds. Webhooks are fast but lossy; the sweep is slow but complete. Each trigger spawns a Claude Code subprocess in one crew role.

Creating a repo fires the builder: it ships v1 from the repo description, one per repo, ever. The agent-work label queues the worker: issue in, PR out — the label IS the queue. The plan-org label on the org's 🌱 Plan this org seed issue launches the planner (org → app suite + roadmap). A repo imported through Forgejo "New Migration" dispatches the migrator, which integrates the import with the platform. A PR that drops its 🏗️ title prefix summons the reviewer, which browser-tests the live preview and posts a verdict. An operator applies ultracode to launch the orchestrator.

Every run gets its own scoped credentials, and the dispatcher meters its cost. The dispatcher is also the money system. It keeps a rolling-window USD spend ledger and consults it at enqueue. Per-org ceilings and breakers bound each org; a fleet-wide governor paces the whole fleet to one Anthropic subscription. Operators steer it live — see Steering the Fleet.

Hands: MCP (open-platform/mcp)

MCP is the platform's API for agents and humans alike. The endpoint is https://mcp.open-platform.sh/mcp, transport Streamable HTTP. Sign in with Forgejo OAuth (browser login) or a Forgejo PAT. The tools act as the caller; Forgejo enforces the caller's permissions on every call. The tools wrap Forgejo (git, PRs, issues, CI), Kubernetes (status, logs, query_db), and the app lifecycle (create_app → release_app → delete_app). Building and operating an app is entirely tool calls — no direct kubectl, no hand-written YAML.

Agent runs get run-scoped tokens. Each token pins to one repo or org and carries a narrow tool allowlist. MCP also serves the /ci/preview and /ci/sync-env endpoints; app CI calls them to provision preview environments and to sync secrets. The connection guide is Connect Your Agent. The full tool table is in Reference.

Substrate: gitops + Flux

Everything the platform runs is a file in open-platform/gitops — Forgejo itself, the dispatcher, MCP, monitoring, and every tenant app. Flux sources that one repo and converges the cluster to it on a 1-minute interval. Platform components live under clusters/local/platform/. Each app gets an overlay under clusters/local/apps/<org>/<app>/<env>/. The overlay holds the namespace, an optional Postgres (CNPG), the TLS certificate, the ingress, and the sealed secrets.

The overlay is the source of truth. Adding one deploys the app.

Warning: Deleting only the namespace does not remove an app — Flux resurrects it. Delete the overlay (with prune) to remove everything.

Every secret in the repo is SOPS-sealed to a single sovereign age key. Details: Platform Internals.

Muscles: the isolated CI pool

All CI runs on a non-privileged pool. A workflow declares runs-on: isolated and gets an ephemeral runner that KEDA scales from zero. The runner uses the open-platform/ci-runner toolchain image, a rootless buildkit sidecar, and a smoke Postgres. The runner pod has no Docker daemon, no ServiceAccount token, and no metadata endpoint; a NetworkPolicy scopes its egress. Builds run buildctl, push the image and the chart to Forgejo packages, and sign them with cosign. Flux's OCIRepositories pull the chart back out.

Node-level pulls of platform images go through a per-node loopback registry mirror at 127.0.0.1:31100. That mirror is frozen into the containerd config at cluster creation. More: CI and Builds.

Ledger: Grafana + Prometheus

Prometheus scrapes /metrics from the dispatcher and from MCP, with 60-day retention. Grafana at https://grafana.open-platform.sh renders the fleet dashboards: allocation and burn, flow dams, dispatcher health, runs and repos. Sign in with your Forgejo account.

Grafana is also a control surface. The Business Forms panels POST flow overrides through the session-gated /flow-api route to the dispatcher. Commands require a signed-in operator session — the Grafana session is the credential.

A freshly-germinated lean daughter strips the monitoring stack, Grafana included. The form-panel route therefore exists only on the parent/full profile. The 🛰 fleet-status issue and the dispatcher's operator flow API (port 9909, e.g. via the plat-flow CLI) work everywhere.

One loop, end to end

One labeled issue becomes a deployed release through these steps:

1. Label an issue agent-work. The webhook wakes the dispatcher.
2. The dispatcher spawns a worker with scoped credentials.
3. The worker pushes commits to an agent/issue-N branch and opens a PR.
4. The check workflow runs on the isolated pool.
5. CI POSTs /ci/preview to MCP; MCP commits a preview overlay to gitops.
6. Flux deploys a real preview environment.
7. The reviewer browser-tests the preview and posts a verdict (Reference lists the verdict strings).
8. A shipping verdict auto-merges the PR.
9. Auto-release builds and pins a new prod chart version.
10. Flux rolls prod, and Grafana meters every dollar of the run.

Every step is a git commit, a webhook, or a tool call. Nothing moves outside the control plane.