ed5f60c · f635c11 · e5aaa29 · d59b618 · 90e85b4 · 29472b7
@@ -1,26 +1,19 @@
# Open Platform — grow your own software platform
# Open Platform
Describe the software you want in plain words, and an AI build crew builds it,
tests it by clicking through it in a real browser, and puts it live at a web
address — on hardware you own. Your ideas go in as sentences; working tools come
out as URLs.
Open Platform is two projects for people and AI agents building software together.
The Forge is one person's place to work, with a private AI crew. The Platform is an
organization's system for shared apps, maintainers, governance and deployment. This
repository, named mitosis, holds the Platform.
This repo is **mitosis** — the part of Open Platform that hands you the whole
thing. Clone it, run one command, and a complete, sovereign platform grows on
your machine: your Git server, CI, registry, and build crew, with fresh keys and
its own identity. Like buying the CD back in the day: it's yours. And when
you're ready, your platform can seed a daughter the same way and hand someone
else the same power.
They meet at the pull request. You pull an organization's code into your forge, work
on it with your crew, and send a clean pull request to the organization's maintainers.
**Not technical? Start with the wiki's plain-language track:**
[The Big Idea](https://git.open-platform.sh/open-platform/mitosis/wiki/The-Big-Idea) ·
[A Day With Your Crew](https://git.open-platform.sh/open-platform/mitosis/wiki/A-Day-With-Your-Crew) ·
[Questions People Ask](https://git.open-platform.sh/open-platform/mitosis/wiki/Questions-People-Ask).
Every platform grown from this repo carries its own copy of these pages in its
**Wiki tab** — the wiki ships in the seed ([`wiki/`](wiki/)) and is the full
guide, from first app to platform internals.
## Get your own forge
## Grow one
Go to [the Forge](https://forge.open-platform.sh/trevato/forge) and follow its README. The Forge needs Bun, not this
repository.
## Run the platform for your organization
```sh
git clone https://git.open-platform.sh/open-platform/mitosis
@@ -28,98 +21,26 @@
cd mitosis
CLAUDE_CODE_OAUTH_TOKEN=<your-token> nix run .#up
```
That's the whole install. Go make coffee — the first run builds the platform
from source and takes **30–60 minutes**, then prints a **YOUR PLATFORM** card
with your domain, your admin logins (Git and Grafana), and exactly how to reach
everything.
The first run builds from source and takes 30 to 60 minutes. Linux is the tested path.
This command was not re-run for this document.
**You need:** [Nix](https://nixos.org/download) with flakes (it brings every
other tool along), Docker with ~4 CPUs and 10 GB, host ports 80/443 free (or set
`HTTP_PORT`/`HTTPS_PORT`), and one Claude credential — `CLAUDE_CODE_OAUTH_TOKEN`
(subscription) or `ANTHROPIC_API_KEY` (API billing). You can add the credential
later; the crew idles until one is set. Linux is the tested path; macOS works on
a best-effort basis. Custom domain: `DOMAIN=acme.local nix run .#up`.
You need:
| First-run stage                        | Rough time |
| -------------------------------------- | ---------- |
| Create the cluster                     | ~2 min     |
| Bootstrap the Git server               | ~2 min     |
| GitOps reconcile + Postgres cold start | 10–20 min  |
| Build the platform's images (CI)       | 15–25 min  |
- [Nix](https://nixos.org/download) with flakes
- Docker with about 4 CPUs and 10 GB
- Ports 80 and 443 free, or `HTTP_PORT` and `HTTPS_PORT` set
- `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY`; the crew idles without one
If a step fails, it tells you which one; the fix is almost always
`k3d cluster delete plat` and re-run — setup is one-shot by design.
The install prints the location of a generated `age` key. That key decrypts every
secret on the platform, so back it up offline. To deploy on AWS, Azure or
DigitalOcean, see [deploy/](deploy/).
> **⚠ Keep your sovereign key safe — forever.** The card points at a generated
> `age` key file. It is the _only_ key to every secret on your platform. Back it
> up somewhere offline you trust.
[EspoDev](https://www.espodev.com) delivers enterprise implementations of the Platform
today. Hosting is coming.
## Use it
## More
The card prints the exact lines, but the shape is: point your machine at the
cluster (`/etc/hosts`), trust the platform's CA, open `https://git.<domain>`,
and click **Use this template** on `open-platform/app-template` — **the name
and description you type are the spec**. Within a minute the crew opens the
first pull request and builds in the open; a validator browser-tests it; it
ships to `https://<app>-<org>.<domain>` with its own documentation in the repo's
Wiki tab, written by the crew as it built.
From there, everything is the wiki's Experience track:
[Build Your First App](https://git.open-platform.sh/open-platform/mitosis/wiki/Build-Your-First-App) ·
[Building with Issues](https://git.open-platform.sh/open-platform/mitosis/wiki/Building-with-Issues) ·
[Orgs and Planning](https://git.open-platform.sh/open-platform/mitosis/wiki/Orgs-and-Planning) ·
[Connect Your Agent](https://git.open-platform.sh/open-platform/mitosis/wiki/Connect-Your-Agent)
(point Claude Code or any MCP harness at `mcp.<domain>` and build from your own
chair).
## Run it
- **Meters and levers**: `https://grafana.<domain>` ships from birth — fleet
  allocation, spend burn, and the flow-control forms.
  [Steering the Fleet](https://git.open-platform.sh/open-platform/mitosis/wiki/Steering-the-Fleet)
- **People and access**: the platform is born with one root-like admin, `plat`,
  and one org it owns, `open-platform`, that holds everything the platform is
  made of. People get their own accounts and orgs; `plat` is for changing the
  platform itself.
  [Users, Teams and Access](https://git.open-platform.sh/open-platform/mitosis/wiki/Users-Teams-and-Access)
- **When it breaks**: a failed setup step → delete the cluster and re-run; agents
  idle → seal a Claude credential (the card prints how); logs →
  `kubectl -n agents logs deploy/agents`.
## Reproduce it — mitosis
Your platform can have children: `PLAT_PAT=<forgejo-pat> nix run .#seed`
snapshots it (add `PUBLISH=1` to version it into your platform's package
registry — then `SEED=latest nix run .#up` grows a child with no file to
carry, integrity-checked against the seed's own integration spec); anyone
with a seed and this repo grows their **own** sovereign platform — fresh
keys, fresh secrets, its own identity, lineage recorded. One
command puts a platform on **AWS, Azure, or DigitalOcean** — bare VMs, single
or 3-VM HA, one DNS record to finish: [deploy/](deploy/). For any other VPS, a
tunnel edge, or adding machines:
[Grow Your Own Platform](https://git.open-platform.sh/open-platform/mitosis/wiki/Grow-Your-Own-Platform)
and [docs/deploy/hetzner-vps.md](docs/deploy/hetzner-vps.md).
## Under the hood
![Open Platform reference architecture](wiki/open-platform-architecture.svg)
![Open Platform reference architecture, dark](wiki/open-platform-architecture-dark.svg)
Forgejo is the whole control plane; a gitops repo is the substrate the cluster
converges on; the platform's own org (`open-platform`) holds the gitops, the
tool server, the crew, the app template and this repo, and the `plat` admin is
the one identity that can change them; the build crew runs on a
non-privileged, isolated CI pool with no escape path to your machine; every
claim is enforced by a cold-start gate that germinates a complete platform in
CI before any change merges. The honest engineering tour:
[Architecture](https://git.open-platform.sh/open-platform/mitosis/wiki/Architecture) ·
[Platform Internals](https://git.open-platform.sh/open-platform/mitosis/wiki/Platform-Internals) ·
[Security Model](https://git.open-platform.sh/open-platform/mitosis/wiki/Security-Model) ·
[CI and Builds](https://git.open-platform.sh/open-platform/mitosis/wiki/CI-and-Builds) ·
[Reference](https://git.open-platform.sh/open-platform/mitosis/wiki/Reference)
## Supported by
Open Platform is supported by [espodev](https://www.espodev.com), who build and
run production implementations for teams that want one delivered. The platform
itself is yours to run — nothing here requires them.
- [Status](docs/STATUS.md): what runs, where data lives, and what is unfinished
- [Platform guide](docs/platform-guide.md): install stages, use, operation and seeds
- [Wiki](wiki/Home.md): the guide that ships with each platform
- [www.open-platform.sh](https://www.open-platform.sh): both projects
@@ -0,0 +1,28 @@
# Open Platform status
This document describes what the Platform runs and what is unproven or unfinished. It is for people evaluating the Platform or the Forge, including people who have run platforms for years.
## For people who have run platforms
- **Runs on:** k3s on one VM, or three VMs with embedded etcd. Terraform covers AWS and DigitalOcean. Bicep covers Azure, on VMs or AKS. Other hosts use `nix run .#up`.
- **Kubernetes parts:** Traefik, Flux, Kyverno, cert-manager, KEDA, CloudNativePG, Prometheus and Grafana.
- **Forgejo:** provides identity, organizations, repositories, issues, pull requests, webhooks, Actions CI and the package registry.
- **Git:** Terraform and Bicep provision machines and ports and do not configure Forgejo. `bin/germinate` installs it, and the layers above depend on it. Plain git is the design goal. It is not sufficient today.
- **Data:** app data is in Postgres. Backups go to an S3-compatible store, which is in-cluster MinIO unless you add an off-site mirror. Secrets are sealed in a gitops repository with SOPS and one `age` key.
- **Crew:** runs on an isolated, non-privileged CI runner pool.
## Unproven or unfinished
- Neither repository has a license file yet.
- The Platform requires Forgejo. Plain git is not enough.
- The Forge writes to GitHub, Forgejo, Gitea and other forges, not GitLab or Bitbucket. Other HTTP(S) git URLs can only be followed, one way.
- No dedicated mechanism lets an app listen to a shared app. An app can receive repository webhooks or call a reachable API.
- Sharing an app means fork, Bring or Forge it. Data, variables and secrets do not come.
- The crew supports Claude Code only and needs a model credential.
- A forge's crew is private to that forge. The model provider sees what the crew reads, and a push to a mirror goes through to its origin.
- The pull-in, crew, pull-request flow, `nix run .#up` and the cloud deployments were not run for this document.
- Apps run contained only on Linux with bubblewrap. On macOS they run uncontained.
- The forge's `docs/THREATS.md` lists protections with no test. No scale figures are published.
- Kyverno enforces image signatures only after a signing key is provisioned.
- Signup at `forge.open-platform.sh` is invite-only. To use a forge today, you run it yourself.
- Hosting for both projects is not available yet.
@@ -0,0 +1,121 @@
# Open Platform guide
This guide holds the install, use and operating detail for Open Platform. It is
for people who run a platform for an organization. For one person's place to work,
see [the Forge](https://forge.open-platform.sh/trevato/forge). [`STATUS.md`](STATUS.md)
describes how the two relate and what is unfinished.
Each repository clone can create a complete platform: a Git server, CI, a package
registry and an AI build crew, with new keys and its own identity. A platform can
create another platform the same way. Each platform carries its own copy of the
wiki ([`wiki/`](../wiki/)) in its Wiki tab.
Pages for readers who are not developers:
- [The Big Idea](https://git.open-platform.sh/open-platform/mitosis/wiki/The-Big-Idea)
- [A Day With Your Crew](https://git.open-platform.sh/open-platform/mitosis/wiki/A-Day-With-Your-Crew)
- [Questions People Ask](https://git.open-platform.sh/open-platform/mitosis/wiki/Questions-People-Ask)
## Grow one
```sh
git clone https://git.open-platform.sh/open-platform/mitosis
cd mitosis
CLAUDE_CODE_OAUTH_TOKEN=<your-token> nix run .#up
```
The first run builds the platform
from source and takes **30–60 minutes**, then prints a **YOUR PLATFORM** card
with your domain, your admin logins (Git and Grafana), and exactly how to reach
everything.
**You need:** [Nix](https://nixos.org/download) with flakes (it brings every
other tool along), Docker with ~4 CPUs and 10 GB, host ports 80/443 free (or set
`HTTP_PORT`/`HTTPS_PORT`), and one Claude credential — `CLAUDE_CODE_OAUTH_TOKEN`
(subscription) or `ANTHROPIC_API_KEY` (API billing). You can add the credential
later; the crew idles until one is set. Linux is the tested path; macOS works on
a best-effort basis. Custom domain: `DOMAIN=acme.local nix run .#up`.
| First-run stage                        | Rough time |
| -------------------------------------- | ---------- |
| Create the cluster                     | ~2 min     |
| Bootstrap the Git server               | ~2 min     |
| GitOps reconcile + Postgres cold start | 10–20 min  |
| Build the platform's images (CI)       | 15–25 min  |
If a step fails, it tells you which one; the fix is almost always
`k3d cluster delete plat` and re-run — setup is one-shot by design.
> **⚠ Keep your sovereign key safe — forever.** The card points at a generated
> `age` key file. It is the _only_ key to every secret on your platform. Back it
> up somewhere offline you trust.
## Use it
The card prints the exact lines, but the shape is: point your machine at the
cluster (`/etc/hosts`), trust the platform's CA, open `https://git.<domain>`,
and click **Use this template** on `open-platform/app-template` — **the name
and description you type are the spec**. Within a minute the crew opens the
first pull request and builds in the open; a validator browser-tests it; it
ships to `https://<app>-<org>.<domain>` with its own documentation in the repo's
Wiki tab, written by the crew as it built.
From there, everything is the wiki's Experience track:
[Build Your First App](https://git.open-platform.sh/open-platform/mitosis/wiki/Build-Your-First-App) ·
[Building with Issues](https://git.open-platform.sh/open-platform/mitosis/wiki/Building-with-Issues) ·
[Orgs and Planning](https://git.open-platform.sh/open-platform/mitosis/wiki/Orgs-and-Planning) ·
[Connect Your Agent](https://git.open-platform.sh/open-platform/mitosis/wiki/Connect-Your-Agent)
(point Claude Code or any MCP harness at `mcp.<domain>` and build from your own
chair).
## Run it
- **Meters and levers**: `https://grafana.<domain>` ships from birth — fleet
  allocation, spend burn, and the flow-control forms.
  [Steering the Fleet](https://git.open-platform.sh/open-platform/mitosis/wiki/Steering-the-Fleet)
- **People and access**: the platform is born with one root-like admin, `plat`,
  and one org it owns, `open-platform`, that holds everything the platform is
  made of. People get their own accounts and orgs; `plat` is for changing the
  platform itself.
  [Users, Teams and Access](https://git.open-platform.sh/open-platform/mitosis/wiki/Users-Teams-and-Access)
- **When it breaks**: a failed setup step → delete the cluster and re-run; agents
  idle → seal a Claude credential (the card prints how); logs →
  `kubectl -n agents logs deploy/agents`.
## Reproduce it — mitosis
Your platform can have children: `PLAT_PAT=<forgejo-pat> nix run .#seed`
snapshots it (add `PUBLISH=1` to version it into your platform's package
registry — then `SEED=latest nix run .#up` grows a child with no file to
carry, integrity-checked against the seed's own integration spec); anyone
with a seed and this repo grows their **own** sovereign platform — fresh
keys, fresh secrets, its own identity, lineage recorded. One
command puts a platform on **AWS, Azure, or DigitalOcean** — bare VMs, single
or 3-VM HA, one DNS record to finish: [deploy/](../deploy/). For any other VPS, a
tunnel edge, or adding machines:
[Grow Your Own Platform](https://git.open-platform.sh/open-platform/mitosis/wiki/Grow-Your-Own-Platform)
and [docs/deploy/hetzner-vps.md](deploy/hetzner-vps.md).
## Under the hood
![Open Platform reference architecture](../wiki/open-platform-architecture.svg)
![Open Platform reference architecture, dark](../wiki/open-platform-architecture-dark.svg)
Forgejo is the whole control plane; a gitops repo is the substrate the cluster
converges on; the platform's own org (`open-platform`) holds the gitops, the
tool server, the crew, the app template and this repo, and the `plat` admin is
the one identity that can change them; the build crew runs on a
non-privileged, isolated CI pool with no escape path to your machine; every
claim is enforced by a cold-start gate that germinates a complete platform in
CI before any change merges. The honest engineering tour:
[Architecture](https://git.open-platform.sh/open-platform/mitosis/wiki/Architecture) ·
[Platform Internals](https://git.open-platform.sh/open-platform/mitosis/wiki/Platform-Internals) ·
[Security Model](https://git.open-platform.sh/open-platform/mitosis/wiki/Security-Model) ·
[CI and Builds](https://git.open-platform.sh/open-platform/mitosis/wiki/CI-and-Builds) ·
[Reference](https://git.open-platform.sh/open-platform/mitosis/wiki/Reference)
## Supported by
Open Platform is supported by [espodev](https://www.espodev.com), who build and
run production implementations for teams that want one delivered. The platform
itself is yours to run — nothing here requires them.
@@ -1,9 +1,25 @@
This platform turns issues into shipped software. You describe what you want in an issue. An AI crew builds it, reviews it, and releases it to a live URL. Everything runs through the Forgejo you are reading right now. Forgejo enforces your permissions on every action, and the crew runs inside the platform's own cluster — never on your machine. Start at [Build Your First App](Build-Your-First-App), or pick a door below. The whole machine fits in one picture: [Architecture](Architecture).
# Open Platform
This wiki describes your Open Platform: how to build apps on it, operate it and
create another platform from it. It is for everyone who uses this platform.
The platform turns issues into running software. You describe a change in an issue,
and an AI crew builds it, reviews it and releases it. Forgejo runs everything and
enforces permissions.
This platform is the organization's half of Open Platform. The other half is
[the Forge](https://forge.open-platform.sh/trevato/forge), one person's place to work with a
private AI crew. A person can pull code from this platform into a forge and send a
pull request back.
> **Not a developer? Start with [The Big Idea](The-Big-Idea)** — the whole platform in plain
> language, no jargon, and everything you need to build your first thing. The technical pages
> below will still be here when you're curious.
## How this platform works
This platform turns issues into shipped software. You describe what you want in an issue. An AI crew builds it, reviews it, and releases it to a live URL. Everything runs through the Forgejo you are reading right now. Forgejo enforces your permissions on every action, and the crew runs inside the platform's own cluster — never on your machine. Start at [Build Your First App](Build-Your-First-App), or pick a door below. The whole machine fits in one picture: [Architecture](Architecture).
## The loop
You describe software in issues. The build crew builds it in pull requests. Every PR gets a real preview environment: its own database, its own URL, its own TLS. A reviewer signs into the preview with a real browser and posts one verdict. On `✅ Ship it`, the PR merges and your app releases to a public URL.
		@@ -1,26 +1,19 @@
1		# Open Platform — grow your own software platform
	1	# Open Platform
2	2
3		Describe the software you want in plain words, and an AI build crew builds it,
4		tests it by clicking through it in a real browser, and puts it live at a web
5		address — on hardware you own. Your ideas go in as sentences; working tools come
6		out as URLs.
	3	Open Platform is two projects for people and AI agents building software together.
	4	The Forge is one person's place to work, with a private AI crew. The Platform is an
	5	organization's system for shared apps, maintainers, governance and deployment. This
	6	repository, named mitosis, holds the Platform.
7	7
8		This repo is mitosis — the part of Open Platform that hands you the whole
9		thing. Clone it, run one command, and a complete, sovereign platform grows on
10		your machine: your Git server, CI, registry, and build crew, with fresh keys and
11		its own identity. Like buying the CD back in the day: it's yours. And when
12		you're ready, your platform can seed a daughter the same way and hand someone
13		else the same power.
	8	They meet at the pull request. You pull an organization's code into your forge, work
	9	on it with your crew, and send a clean pull request to the organization's maintainers.
14	10
15		Not technical? Start with the wiki's plain-language track:
16		[The Big Idea](https://git.open-platform.sh/open-platform/mitosis/wiki/The-Big-Idea) ·
17		[A Day With Your Crew](https://git.open-platform.sh/open-platform/mitosis/wiki/A-Day-With-Your-Crew) ·
18		[Questions People Ask](https://git.open-platform.sh/open-platform/mitosis/wiki/Questions-People-Ask).
19		Every platform grown from this repo carries its own copy of these pages in its
20		Wiki tab — the wiki ships in the seed ([`wiki/`](wiki/)) and is the full
21		guide, from first app to platform internals.
	11	## Get your own forge
22	12
23		## Grow one
	13	Go to [the Forge](https://forge.open-platform.sh/trevato/forge) and follow its README. The Forge needs Bun, not this
	14	repository.
	15
	16	## Run the platform for your organization
24	17
25	18	```sh
26	19	git clone https://git.open-platform.sh/open-platform/mitosis
		@@ -28,98 +21,26 @@ cd mitosis
28	21	CLAUDE_CODE_OAUTH_TOKEN=<your-token> nix run .#up
29	22	```
30	23
31		That's the whole install. Go make coffee — the first run builds the platform
32		from source and takes 30–60 minutes, then prints a YOUR PLATFORM card
33		with your domain, your admin logins (Git and Grafana), and exactly how to reach
34		everything.
	24	The first run builds from source and takes 30 to 60 minutes. Linux is the tested path.
	25	This command was not re-run for this document.
35	26
36		You need: [Nix](https://nixos.org/download) with flakes (it brings every
37		other tool along), Docker with ~4 CPUs and 10 GB, host ports 80/443 free (or set
38		`HTTP_PORT`/`HTTPS_PORT`), and one Claude credential — `CLAUDE_CODE_OAUTH_TOKEN`
39		(subscription) or `ANTHROPIC_API_KEY` (API billing). You can add the credential
40		later; the crew idles until one is set. Linux is the tested path; macOS works on
41		a best-effort basis. Custom domain: `DOMAIN=acme.local nix run .#up`.
	27	You need:
42	28
43		\| First-run stage \| Rough time \|
44		\| -------------------------------------- \| ---------- \|
45		\| Create the cluster \| ~2 min \|
46		\| Bootstrap the Git server \| ~2 min \|
47		\| GitOps reconcile + Postgres cold start \| 10–20 min \|
48		\| Build the platform's images (CI) \| 15–25 min \|
	29	- [Nix](https://nixos.org/download) with flakes
	30	- Docker with about 4 CPUs and 10 GB
	31	- Ports 80 and 443 free, or `HTTP_PORT` and `HTTPS_PORT` set
	32	- `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY`; the crew idles without one
49	33
50		If a step fails, it tells you which one; the fix is almost always
51		`k3d cluster delete plat` and re-run — setup is one-shot by design.
	34	The install prints the location of a generated `age` key. That key decrypts every
	35	secret on the platform, so back it up offline. To deploy on AWS, Azure or
	36	DigitalOcean, see [deploy/](deploy/).
52	37
53		> ⚠ Keep your sovereign key safe — forever. The card points at a generated
54		> `age` key file. It is the _only_ key to every secret on your platform. Back it
55		> up somewhere offline you trust.
	38	[EspoDev](https://www.espodev.com) delivers enterprise implementations of the Platform
	39	today. Hosting is coming.
56	40
57		## Use it
	41	## More
58	42
59		The card prints the exact lines, but the shape is: point your machine at the
60		cluster (`/etc/hosts`), trust the platform's CA, open `https://git.<domain>`,
61		and click Use this template on `open-platform/app-template` — **the name
62		and description you type are the spec**. Within a minute the crew opens the
63		first pull request and builds in the open; a validator browser-tests it; it
64		ships to `https://<app>-<org>.<domain>` with its own documentation in the repo's
65		Wiki tab, written by the crew as it built.
66
67		From there, everything is the wiki's Experience track:
68		[Build Your First App](https://git.open-platform.sh/open-platform/mitosis/wiki/Build-Your-First-App) ·
69		[Building with Issues](https://git.open-platform.sh/open-platform/mitosis/wiki/Building-with-Issues) ·
70		[Orgs and Planning](https://git.open-platform.sh/open-platform/mitosis/wiki/Orgs-and-Planning) ·
71		[Connect Your Agent](https://git.open-platform.sh/open-platform/mitosis/wiki/Connect-Your-Agent)
72		(point Claude Code or any MCP harness at `mcp.<domain>` and build from your own
73		chair).
74
75		## Run it
76
77		- Meters and levers: `https://grafana.<domain>` ships from birth — fleet
78		allocation, spend burn, and the flow-control forms.
79		[Steering the Fleet](https://git.open-platform.sh/open-platform/mitosis/wiki/Steering-the-Fleet)
80		- People and access: the platform is born with one root-like admin, `plat`,
81		and one org it owns, `open-platform`, that holds everything the platform is
82		made of. People get their own accounts and orgs; `plat` is for changing the
83		platform itself.
84		[Users, Teams and Access](https://git.open-platform.sh/open-platform/mitosis/wiki/Users-Teams-and-Access)
85		- When it breaks: a failed setup step → delete the cluster and re-run; agents
86		idle → seal a Claude credential (the card prints how); logs →
87		`kubectl -n agents logs deploy/agents`.
88
89		## Reproduce it — mitosis
90
91		Your platform can have children: `PLAT_PAT=<forgejo-pat> nix run .#seed`
92		snapshots it (add `PUBLISH=1` to version it into your platform's package
93		registry — then `SEED=latest nix run .#up` grows a child with no file to
94		carry, integrity-checked against the seed's own integration spec); anyone
95		with a seed and this repo grows their own sovereign platform — fresh
96		keys, fresh secrets, its own identity, lineage recorded. One
97		command puts a platform on AWS, Azure, or DigitalOcean — bare VMs, single
98		or 3-VM HA, one DNS record to finish: [deploy/](deploy/). For any other VPS, a
99		tunnel edge, or adding machines:
100		[Grow Your Own Platform](https://git.open-platform.sh/open-platform/mitosis/wiki/Grow-Your-Own-Platform)
101		and [docs/deploy/hetzner-vps.md](docs/deploy/hetzner-vps.md).
102
103		## Under the hood
104
105		![Open Platform reference architecture](wiki/open-platform-architecture.svg)
106		![Open Platform reference architecture, dark](wiki/open-platform-architecture-dark.svg)
107
108		Forgejo is the whole control plane; a gitops repo is the substrate the cluster
109		converges on; the platform's own org (`open-platform`) holds the gitops, the
110		tool server, the crew, the app template and this repo, and the `plat` admin is
111		the one identity that can change them; the build crew runs on a
112		non-privileged, isolated CI pool with no escape path to your machine; every
113		claim is enforced by a cold-start gate that germinates a complete platform in
114		CI before any change merges. The honest engineering tour:
115		[Architecture](https://git.open-platform.sh/open-platform/mitosis/wiki/Architecture) ·
116		[Platform Internals](https://git.open-platform.sh/open-platform/mitosis/wiki/Platform-Internals) ·
117		[Security Model](https://git.open-platform.sh/open-platform/mitosis/wiki/Security-Model) ·
118		[CI and Builds](https://git.open-platform.sh/open-platform/mitosis/wiki/CI-and-Builds) ·
119		[Reference](https://git.open-platform.sh/open-platform/mitosis/wiki/Reference)
120
121		## Supported by
122
123		Open Platform is supported by [espodev](https://www.espodev.com), who build and
124		run production implementations for teams that want one delivered. The platform
125		itself is yours to run — nothing here requires them.
	43	- [Status](docs/STATUS.md): what runs, where data lives, and what is unfinished
	44	- [Platform guide](docs/platform-guide.md): install stages, use, operation and seeds
	45	- [Wiki](wiki/Home.md): the guide that ships with each platform
	46	- [www.open-platform.sh](https://www.open-platform.sh): both projects
		@@ -0,0 +1,28 @@
	1	# Open Platform status
	2
	3	This document describes what the Platform runs and what is unproven or unfinished. It is for people evaluating the Platform or the Forge, including people who have run platforms for years.
	4
	5	## For people who have run platforms
	6
	7	- Runs on: k3s on one VM, or three VMs with embedded etcd. Terraform covers AWS and DigitalOcean. Bicep covers Azure, on VMs or AKS. Other hosts use `nix run .#up`.
	8	- Kubernetes parts: Traefik, Flux, Kyverno, cert-manager, KEDA, CloudNativePG, Prometheus and Grafana.
	9	- Forgejo: provides identity, organizations, repositories, issues, pull requests, webhooks, Actions CI and the package registry.
	10	- Git: Terraform and Bicep provision machines and ports and do not configure Forgejo. `bin/germinate` installs it, and the layers above depend on it. Plain git is the design goal. It is not sufficient today.
	11	- Data: app data is in Postgres. Backups go to an S3-compatible store, which is in-cluster MinIO unless you add an off-site mirror. Secrets are sealed in a gitops repository with SOPS and one `age` key.
	12	- Crew: runs on an isolated, non-privileged CI runner pool.
	13
	14	## Unproven or unfinished
	15
	16	- Neither repository has a license file yet.
	17	- The Platform requires Forgejo. Plain git is not enough.
	18	- The Forge writes to GitHub, Forgejo, Gitea and other forges, not GitLab or Bitbucket. Other HTTP(S) git URLs can only be followed, one way.
	19	- No dedicated mechanism lets an app listen to a shared app. An app can receive repository webhooks or call a reachable API.
	20	- Sharing an app means fork, Bring or Forge it. Data, variables and secrets do not come.
	21	- The crew supports Claude Code only and needs a model credential.
	22	- A forge's crew is private to that forge. The model provider sees what the crew reads, and a push to a mirror goes through to its origin.
	23	- The pull-in, crew, pull-request flow, `nix run .#up` and the cloud deployments were not run for this document.
	24	- Apps run contained only on Linux with bubblewrap. On macOS they run uncontained.
	25	- The forge's `docs/THREATS.md` lists protections with no test. No scale figures are published.
	26	- Kyverno enforces image signatures only after a signing key is provisioned.
	27	- Signup at `forge.open-platform.sh` is invite-only. To use a forge today, you run it yourself.
	28	- Hosting for both projects is not available yet.
		@@ -0,0 +1,121 @@
	1	# Open Platform guide
	2
	3	This guide holds the install, use and operating detail for Open Platform. It is
	4	for people who run a platform for an organization. For one person's place to work,
	5	see [the Forge](https://forge.open-platform.sh/trevato/forge). [`STATUS.md`](STATUS.md)
	6	describes how the two relate and what is unfinished.
	7
	8	Each repository clone can create a complete platform: a Git server, CI, a package
	9	registry and an AI build crew, with new keys and its own identity. A platform can
	10	create another platform the same way. Each platform carries its own copy of the
	11	wiki ([`wiki/`](../wiki/)) in its Wiki tab.
	12
	13	Pages for readers who are not developers:
	14
	15	- [The Big Idea](https://git.open-platform.sh/open-platform/mitosis/wiki/The-Big-Idea)
	16	- [A Day With Your Crew](https://git.open-platform.sh/open-platform/mitosis/wiki/A-Day-With-Your-Crew)
	17	- [Questions People Ask](https://git.open-platform.sh/open-platform/mitosis/wiki/Questions-People-Ask)
	18
	19	## Grow one
	20
	21	```sh
	22	git clone https://git.open-platform.sh/open-platform/mitosis
	23	cd mitosis
	24	CLAUDE_CODE_OAUTH_TOKEN=<your-token> nix run .#up
	25	```
	26
	27	The first run builds the platform
	28	from source and takes 30–60 minutes, then prints a YOUR PLATFORM card
	29	with your domain, your admin logins (Git and Grafana), and exactly how to reach
	30	everything.
	31
	32	You need: [Nix](https://nixos.org/download) with flakes (it brings every
	33	other tool along), Docker with ~4 CPUs and 10 GB, host ports 80/443 free (or set
	34	`HTTP_PORT`/`HTTPS_PORT`), and one Claude credential — `CLAUDE_CODE_OAUTH_TOKEN`
	35	(subscription) or `ANTHROPIC_API_KEY` (API billing). You can add the credential
	36	later; the crew idles until one is set. Linux is the tested path; macOS works on
	37	a best-effort basis. Custom domain: `DOMAIN=acme.local nix run .#up`.
	38
	39	\| First-run stage \| Rough time \|
	40	\| -------------------------------------- \| ---------- \|
	41	\| Create the cluster \| ~2 min \|
	42	\| Bootstrap the Git server \| ~2 min \|
	43	\| GitOps reconcile + Postgres cold start \| 10–20 min \|
	44	\| Build the platform's images (CI) \| 15–25 min \|
	45
	46	If a step fails, it tells you which one; the fix is almost always
	47	`k3d cluster delete plat` and re-run — setup is one-shot by design.
	48
	49	> ⚠ Keep your sovereign key safe — forever. The card points at a generated
	50	> `age` key file. It is the _only_ key to every secret on your platform. Back it
	51	> up somewhere offline you trust.
	52
	53	## Use it
	54
	55	The card prints the exact lines, but the shape is: point your machine at the
	56	cluster (`/etc/hosts`), trust the platform's CA, open `https://git.<domain>`,
	57	and click Use this template on `open-platform/app-template` — **the name
	58	and description you type are the spec**. Within a minute the crew opens the
	59	first pull request and builds in the open; a validator browser-tests it; it
	60	ships to `https://<app>-<org>.<domain>` with its own documentation in the repo's
	61	Wiki tab, written by the crew as it built.
	62
	63	From there, everything is the wiki's Experience track:
	64	[Build Your First App](https://git.open-platform.sh/open-platform/mitosis/wiki/Build-Your-First-App) ·
	65	[Building with Issues](https://git.open-platform.sh/open-platform/mitosis/wiki/Building-with-Issues) ·
	66	[Orgs and Planning](https://git.open-platform.sh/open-platform/mitosis/wiki/Orgs-and-Planning) ·
	67	[Connect Your Agent](https://git.open-platform.sh/open-platform/mitosis/wiki/Connect-Your-Agent)
	68	(point Claude Code or any MCP harness at `mcp.<domain>` and build from your own
	69	chair).
	70
	71	## Run it
	72
	73	- Meters and levers: `https://grafana.<domain>` ships from birth — fleet
	74	allocation, spend burn, and the flow-control forms.
	75	[Steering the Fleet](https://git.open-platform.sh/open-platform/mitosis/wiki/Steering-the-Fleet)
	76	- People and access: the platform is born with one root-like admin, `plat`,
	77	and one org it owns, `open-platform`, that holds everything the platform is
	78	made of. People get their own accounts and orgs; `plat` is for changing the
	79	platform itself.
	80	[Users, Teams and Access](https://git.open-platform.sh/open-platform/mitosis/wiki/Users-Teams-and-Access)
	81	- When it breaks: a failed setup step → delete the cluster and re-run; agents
	82	idle → seal a Claude credential (the card prints how); logs →
	83	`kubectl -n agents logs deploy/agents`.
	84
	85	## Reproduce it — mitosis
	86
	87	Your platform can have children: `PLAT_PAT=<forgejo-pat> nix run .#seed`
	88	snapshots it (add `PUBLISH=1` to version it into your platform's package
	89	registry — then `SEED=latest nix run .#up` grows a child with no file to
	90	carry, integrity-checked against the seed's own integration spec); anyone
	91	with a seed and this repo grows their own sovereign platform — fresh
	92	keys, fresh secrets, its own identity, lineage recorded. One
	93	command puts a platform on AWS, Azure, or DigitalOcean — bare VMs, single
	94	or 3-VM HA, one DNS record to finish: [deploy/](../deploy/). For any other VPS, a
	95	tunnel edge, or adding machines:
	96	[Grow Your Own Platform](https://git.open-platform.sh/open-platform/mitosis/wiki/Grow-Your-Own-Platform)
	97	and [docs/deploy/hetzner-vps.md](deploy/hetzner-vps.md).
	98
	99	## Under the hood
	100
	101	![Open Platform reference architecture](../wiki/open-platform-architecture.svg)
	102	![Open Platform reference architecture, dark](../wiki/open-platform-architecture-dark.svg)
	103
	104	Forgejo is the whole control plane; a gitops repo is the substrate the cluster
	105	converges on; the platform's own org (`open-platform`) holds the gitops, the
	106	tool server, the crew, the app template and this repo, and the `plat` admin is
	107	the one identity that can change them; the build crew runs on a
	108	non-privileged, isolated CI pool with no escape path to your machine; every
	109	claim is enforced by a cold-start gate that germinates a complete platform in
	110	CI before any change merges. The honest engineering tour:
	111	[Architecture](https://git.open-platform.sh/open-platform/mitosis/wiki/Architecture) ·
	112	[Platform Internals](https://git.open-platform.sh/open-platform/mitosis/wiki/Platform-Internals) ·
	113	[Security Model](https://git.open-platform.sh/open-platform/mitosis/wiki/Security-Model) ·
	114	[CI and Builds](https://git.open-platform.sh/open-platform/mitosis/wiki/CI-and-Builds) ·
	115	[Reference](https://git.open-platform.sh/open-platform/mitosis/wiki/Reference)
	116
	117	## Supported by
	118
	119	Open Platform is supported by [espodev](https://www.espodev.com), who build and
	120	run production implementations for teams that want one delivered. The platform
	121	itself is yours to run — nothing here requires them.
		@@ -1,9 +1,25 @@
1		This platform turns issues into shipped software. You describe what you want in an issue. An AI crew builds it, reviews it, and releases it to a live URL. Everything runs through the Forgejo you are reading right now. Forgejo enforces your permissions on every action, and the crew runs inside the platform's own cluster — never on your machine. Start at [Build Your First App](Build-Your-First-App), or pick a door below. The whole machine fits in one picture: [Architecture](Architecture).
	1	# Open Platform
	2
	3	This wiki describes your Open Platform: how to build apps on it, operate it and
	4	create another platform from it. It is for everyone who uses this platform.
	5
	6	The platform turns issues into running software. You describe a change in an issue,
	7	and an AI crew builds it, reviews it and releases it. Forgejo runs everything and
	8	enforces permissions.
	9
	10	This platform is the organization's half of Open Platform. The other half is
	11	[the Forge](https://forge.open-platform.sh/trevato/forge), one person's place to work with a
	12	private AI crew. A person can pull code from this platform into a forge and send a
	13	pull request back.
2	14
3	15	> Not a developer? Start with [The Big Idea](The-Big-Idea) — the whole platform in plain
4	16	> language, no jargon, and everything you need to build your first thing. The technical pages
5	17	> below will still be here when you're curious.
6	18
	19	## How this platform works
	20
	21	This platform turns issues into shipped software. You describe what you want in an issue. An AI crew builds it, reviews it, and releases it to a live URL. Everything runs through the Forgejo you are reading right now. Forgejo enforces your permissions on every action, and the crew runs inside the platform's own cluster — never on your machine. Start at [Build Your First App](Build-Your-First-App), or pick a door below. The whole machine fits in one picture: [Architecture](Architecture).
	22
7	23	## The loop
8	24
9	25	You describe software in issues. The build crew builds it in pull requests. Every PR gets a real preview environment: its own database, its own URL, its own TLS. A reviewer signs into the preview with a real browser and posts one verdict. On `✅ Ship it`, the PR merges and your app releases to a public URL.