T4 Code -> T4 Local Service -> shared OMP adapter -> official OMP -> local files
-T4 Code -> T4 Hub -> managed runtime -> shared OMP adapter -> official OMP -> CephFS
+T4 Code -> T4 Hub -> managed runtime -> shared OMP adapter -> official OMP -> RWX project
\-> Workstation Runner -> shared OMP adapter -> official OMP -> local filesT4 Hub integrates source control and CI/CD activity into durable managed @@ -768,15 +769,24 @@
Users interact with T4 Code, T4 Local Service, T4 Hub, and optionally a - Workstation Runner or T4 Node. Kubernetes, containerd, PostgreSQL - replication, storage placement, and telemetry topology remain - managed-profile implementation details. + Workstation Runner or T4 Node. Cluster administrators may install the + portable T4 charts against existing services or use the optional T4 Stack + profile. Provider lifecycle and topology remain outside the T4 operator.
The following invariants apply to managed Hub sessions:
@@ -806,6 +816,12 @@This topology covers Personal Hub and HA Hub. T4 Local has no Kubernetes, - PostgreSQL, CephFS, MinIO, or Grafana dependency; its client connects to - native Local Service over loopback. + PostgreSQL, network filesystem, object-store, or telemetry dependency; its + client connects to native Local Service over loopback.
- In a single-node installation, the one Linux machine is both T4 Hub and T4 - Node. In an HA installation, Hub API, database, operator, storage, and - telemetry replicas are distributed across the cluster. Clients use one - stable Tailnet service address and do not select a control-plane replica. + In a single-node installation, one Linux machine may host T4 and compact + dependency instances. In HA mode, T4 API and operator replicas are + distributed independently from provider-managed database, storage, and + telemetry replicas. Clients use one stable Tailnet service address and do + not select a control-plane replica.
A Linux Hub machine may be a dedicated mini PC, home or office server, NAS-hosted VM, cloud VM, or Linux workstation. macOS and Windows run T4 Code and may run native T4 Local Service; macOS and Linux may additionally - register as Workstation Runners. Hub and k3s node implementations remain + register as Workstation Runners. Managed T4 node implementations remain Linux-only, so a native Mac never needs a managed Linux VM for T4 Local.
- Rook-managed CephFS is the selected live shared filesystem. T4 provisions
- one CephFS subvolume or equivalent isolation boundary per project and
- mounts it through the Ceph CSI driver as RWX storage. Ceph placement must
- use explicit nodes and devices; the installer never consumes an unapproved
- disk automatically.
+ Managed deployments consume an administrator-selected Kubernetes
+ StorageClass that provisions real RWX volumes. T4Workspace
+ records the requested class and size; the T4 operator creates the PVC and
+ mounts the bound claim into session pods. It does not install a CSI
+ driver, create backend-specific CRs, select disks, or change storage
+ topology.
- A single-node profile runs one nonredundant Ceph monitor, manager, - metadata service, and size-one data/metadata pools. The GUI labels this - state as unprotected and requires the user to select suitable Ceph - storage. When two additional storage nodes join, T4 distributes monitors, - enables a standby metadata service, changes pool placement to the host - failure domain, raises replication to three, waits for backfill, and - reports HA only after Ceph returns healthy. + The optional T4 Stack profile may install a vetted default storage chart + for users who want a guided single-machine path. That provider retains its + own operator, CRDs, RBAC, status, upgrades, and recovery procedures. An + existing cluster may instead supply any implementation that passes the + same contract.
- CephFS remains subject to a representative conformance suite covering real
- OMP worktree concurrency, large repositories, package trees, pod and node
- failure, expansion from one to three nodes, metadata-service failover,
- pool backfill, snapshot, restore, and
- git fsck integrity. This validates the selected
- implementation rather than reopening the provider decision.
+ Storage conformance covers real OMP worktree concurrency, POSIX locking,
+ large repositories, package trees, pod and node failure, remount,
+ snapshot, restore, stale-writer fencing, metadata performance, and
+ git fsck integrity. A provider name or RWX declaration alone
+ is not evidence.
- MinIO is object storage rather than the live POSIX filesystem. It stores - artifacts, uploads, transcript and log chunks, filesystem backups, - database backups, and observability objects. + Optional S3-compatible object storage is a separate contract for immutable + artifacts, uploads, large transcript or log chunks, and backup objects. T4 + receives an endpoint and credential reference; it does not expose + provider-specific object-store CRs. The initial compact profile may keep + bounded objects on RWX storage and omit S3 entirely.
@@ -1485,13 +1515,14 @@
| Layer | -Selected technology | +T4 choice or external contract | |
|---|---|---|---|
| Cluster | -k3s using standard Kubernetes APIs | +Kubernetes 1.30+; k3s is the optional T4 Stack default | |
| Container runtime | @@ -1539,18 +1570,18 @@|||
| Product database | -PostgreSQL managed by CloudNativePG in HA mode | ++ PostgreSQL protocol; an existing service or an optional stack + profile managed by a dedicated PostgreSQL operator + | |
| Shared filesystem | -- Rook-managed CephFS exposed through the Ceph CSI driver as RWX - project storage - | +Administrator-selected, conformance-tested RWX StorageClass | |
| Object storage | -MinIO Community Edition | +Optional S3-compatible endpoint and credential reference | |
| Source workflow | @@ -1564,28 +1595,11 @@|||
| Dashboards | -Grafana OSS | -||
| Telemetry collection | -Grafana Alloy | -||
| Metrics | -Grafana Mimir | -||
| Logs | -Grafana Loki | -||
| Traces | -Grafana Tempo | -||
| Instrumentation | -OpenTelemetry | +Observability | ++ Prometheus-format metrics and OpenTelemetry export to an optional + administrator-selected backend + |
| Secrets | @@ -1597,11 +1611,11 @@
- The self-hosted software stack can operate without software license fees, - subject to the applicable open-source and source-available licenses. - Tailscale's hosted control plane, GitHub plans, hardware, bandwidth, store - accounts, and operational support may incur costs. AGPL components must - remain license-compliant, especially if modified or redistributed. + Provider choices must satisfy their own licenses and remain independently + replaceable. The optional T4 Stack must not bundle a copyleft or + source-available dependency by default without an explicit distribution + and network-use compliance decision. Hosted services, hardware, bandwidth, + store accounts, and operational support may still incur costs.
@@ -1613,7 +1627,8 @@
T4 Local Service runs natively on the same macOS or Linux workstation as OMP and the project. Flutter connects over loopback by default. No Linux - VM, k3s, PostgreSQL, CephFS, MinIO, or Grafana service is required. + VM, Kubernetes cluster, PostgreSQL service, network filesystem, object + store, or telemetry backend is required.
Benefits
- One always-on Linux computer or VM runs the full managed stack and managed + One always-on Linux computer or VM runs the T4 components and managed runtimes. It may sit on a desk, on a LAN, or remotely; desktop and mobile - clients connect through a stable Tailscale service. CephFS, PostgreSQL, - and telemetry use deliberate size-one compact topology. + clients connect through a stable Tailscale service. The optional T4 Stack + chart supplies a tested compact path, while every database, storage, and + telemetry dependency keeps an independent ownership boundary.
Benefits
- At least three suitable Linux machines run k3s with embedded-etcd quorum, - distributed Hub replicas, PostgreSQL replicas, replicated CephFS, and - schedulable runtime capacity. + At least three suitable Linux failure domains run Kubernetes quorum, + distributed T4 replicas, a highly available PostgreSQL service, replicated + provider-managed RWX storage, and schedulable runtime capacity.
Benefits
Two nodes may add capacity but are not labeled HA because they cannot preserve quorum after an arbitrary partition. No managed session moves - across nodes until hard Ceph writer fencing and owner-epoch recovery pass - the failure matrix. + across nodes until hard storage-writer fencing and owner-epoch recovery + pass the failure matrix.
-- An explicit advanced path may support an existing k3s cluster, dedicated - control/storage/worker roles, external PostgreSQL or object storage, - custom storage classes, and specialized runner pools. Unsupported - combinations are rejected rather than accepted optimistically. + The portable charts support an existing conformant Kubernetes cluster, + PostgreSQL service, RWX StorageClass, optional S3-compatible endpoint, + ingress, and telemetry backend. The optional T4 Stack is a convenience + distribution of the same T4 artifacts, not a second architecture and not + authority for the referenced providers.
@@ -1743,8 +1760,9 @@
- Users do not run kubectl, edit Helm values, manage database
- credentials, or place replicas manually.
+ Stack-profile users do not need to run kubectl or place
+ replicas manually. Existing-cluster administrators use Helm values and
+ Secret references to bind T4 to services they already operate.
- The GUI exposes Make highly available or
- Add node. T4 enrolls additional Linux machines, expands
- embedded-etcd quorum, creates PostgreSQL and storage replicas, expands or
- migrates MinIO safely, adds Hub replicas, rebalances workloads, and runs
- failure checks before reporting HA.
+ The GUI may expose Make highly available or
+ Add node for a tested T4 Stack profile. T4 may enroll nodes,
+ expand Kubernetes quorum, and add T4 replicas, but provider-specific
+ database and storage expansion remains the responsibility of their own
+ operators. The installer coordinates health gates without assuming that
+ the T4 operator owns those topology changes.
The client endpoint, project identifiers, session history, worktree paths, @@ -1919,9 +1941,9 @@
- Ordinary users choose among versioned, tested profiles. Arbitrary - independent replica counts and service placements remain an advanced - operator concern. + Ordinary users choose among versioned, tested T4 Stack profiles. + Existing-cluster administrators choose provider topology through the + providers' own APIs, not through T4 custom resources.
@@ -1945,28 +1967,27 @@
These events are persisted and shown in T4 Code. The GUI does not infer - authoritative progress by scraping terminal text or querying Grafana. + authoritative progress by scraping terminal text or querying an + observability backend.
The optional managed self-hosted Grafana LGTM stack is:
-- No Prometheus server is required. Alloy may scrape Prometheus-format - metrics exposed by Kubernetes and its components. + T4 exposes bounded Prometheus-format metrics, structured logs, health + endpoints, and OpenTelemetry signals. An administrator may connect + Grafana, Prometheus, an LGTM deployment, or another compatible backend. + The T4 operator does not install or reconcile those systems. +
+
+ The portable chart may create narrowly scoped integration resources such
+ as a ServiceMonitor or alert rules only when their CRDs
+ already exist and the administrator enables them. The optional T4 Stack
+ may offer a separately owned observability profile; it is not required for
+ product correctness.
- Personal Hub uses compact, bounded-retention deployments; HA Hub may use - distributed deployments. Observability failure cannot prevent session - execution or alter durable product state. T4 Local requires no Grafana - services and uses bounded native diagnostics. + Observability failure cannot prevent session execution or alter durable + product state. T4 Local requires no external telemetry service and uses + bounded native diagnostics.
T4 Local preserves native filesystem and toolchain performance. Managed - benchmarks emphasize CephFS metadata-heavy work: Git status, worktree + benchmarks emphasize RWX metadata-heavy work: Git status, worktree creation, package trees, file watching, dependency installation, search, - large builds, and concurrent OMP sessions. Personal Hub uses one replica - of each required service, size-one Ceph pools, conservative database - buffers, bounded telemetry retention, trace sampling, node-local - disposable caches, and suspended idle runtime pods. It adds no service - mesh, Kafka, NATS, or per-runtime Tailnet sidecars without measured need. + large builds, and concurrent OMP sessions. Personal Hub uses compact T4 + replicas, conservative database buffers, bounded telemetry retention, + node-local disposable caches, and suspended idle runtime pods. It adds no + service mesh, Kafka, NATS, or per-runtime Tailnet sidecars without + measured need.
- The installer does not stabilize in parallel with changing profile - semantics. k3s datastore, Ceph pool, PostgreSQL, and MinIO topology - migrations are never run concurrently during expansion. Those are serial - evidence gates because concurrent migrations make failure attribution and - rollback ambiguous. + T4 chart semantics and provider contracts stabilize before the optional + installer. Provider topology migrations remain owned and reported by their + respective operators. A T4 Stack expansion coordinates these independent + operations serially so failure attribution and rollback stay explicit.
@@ -2248,23 +2274,24 @@
indeterminate
unless OMP proves durable acceptance. Close the workstation service and
- confirm no other machine claims the local session. This gate has no k3s,
- PostgreSQL, CephFS, MinIO, or Grafana dependency.
+ confirm no other machine claims the local session. This gate has no
+ Kubernetes, PostgreSQL, network-filesystem, object-store, or telemetry
+ dependency.
- Install the first real Linux node through the intended path: k3s with - embedded etcd from the beginning, containerd, a stable Tailscale - Kubernetes service identity, one CloudNativePG instance, explicitly - enrolled size-one Rook/CephFS pools, MinIO, and a compact nonblocking - Grafana LGTM profile. Use one versioned release chart; Docker, Docker - Desktop, k3d, and a separate Docker Compose architecture are not required. + Prove both supported installation forms: portable T4 charts against + existing PostgreSQL, ingress, and RWX services; and the optional T4 Stack + on one real Linux node. Both forms deploy the same Hub, operator, and + runtime artifacts. Docker Desktop, k3d, and a separate Docker Compose + architecture are not required.
- Before running OMP, mount one CephFS project from multiple disposable test - pods, reboot the node, remount it, and verify content and filesystem - semantics. PostgreSQL, MinIO, Ceph, and telemetry health must be - distinguishable; Grafana impairment must never block product commands. + Before running OMP, mount one conformant RWX project from multiple + disposable pods, reboot the node, remount it, and verify filesystem + semantics. Database, filesystem, optional object-store, and telemetry + health remain distinguishable; external-service impairment cannot grant + the T4 operator provider authority or corrupt product commands.
- Create a coordinated PostgreSQL, CephFS, and MinIO backup generation on an - independent destination, wipe the test installation, and restore it onto a - clean host. Backup creation without a successful bare-host restore is not - evidence. + Create a coordinated PostgreSQL, shared-filesystem, and optional + object-store backup generation on an independent destination, wipe the + test installation, and restore it onto a clean host. Backup creation + without a successful bare-host restore is not evidence.
@@ -2330,20 +2359,20 @@
Turn the exact managed automation used by Gates 2B through 4 into the - signed T4 Node bootstrap and the Flutter setup flow. Installation, health + signed T4 Node bootstrap and Flutter setup flow. Installation, health checks, support collection, update, failed-update stop, rollback, and recovery must be repeatable from a clean supported Linux image without - requiring the user to understand Kubernetes, Ceph, PostgreSQL, or MinIO. + making an ordinary stack-profile user administer Kubernetes or its + independently owned providers.
- Add two validated Linux nodes and perform topology changes serially: - expand embedded-etcd quorum, add Ceph OSDs and monitors, raise CephFS - pools from size one to host-distributed size three and wait for backfill, - add CloudNativePG replicas, migrate or expand MinIO through a proven path, - add Hub and operator replicas, then validate the stable Tailnet endpoint. - After every store reports healthy, remove one node and prove continued - operation before applying the HA label. + Add two validated Linux nodes and perform changes serially: expand + Kubernetes quorum, request provider-owned database and storage expansion, + add Hub and T4 operator replicas, then validate the stable Tailnet + endpoint. Every provider must report its own healthy state, and the T4 + operator must remain unable to mutate provider topology. Remove one node + and prove continued operation before applying the HA label.
@@ -2370,13 +2399,13 @@
/dev/disk/by-id, with no filesystem signatures or data to
- preserve, for Ceph.
+ Storage capacity and any provider-specific devices required by the
+ selected optional T4 Stack profile, explicitly approved and containing
+ no data to preserve.