diff --git a/docs/ADOPTION.md b/docs/ADOPTION.md new file mode 100644 index 0000000..caf7294 --- /dev/null +++ b/docs/ADOPTION.md @@ -0,0 +1,158 @@ +# Adopt GroundControl + +GroundControl is a self-hosted, single-tenant control plane for operating Docker Compose applications on infrastructure you own. It is designed for founders and lean teams that want agents such as ChatGPT to inspect and operate deployments without receiving SSH keys or unrestricted shell access. + +## Choose your starting point + +### Evaluate privately + +Use this when you want to inspect the product before creating a public management endpoint. + +```bash +curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install \ + | sudo bash -s -- --json +``` + +The installer binds GroundControl to loopback, returns a short-lived one-time claim URL, and leaves publication as a separate operator decision. + +### Install interactively + +```bash +curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install \ + | sudo bash +``` + +For a remote VPS, create the SSH tunnel printed by the installer, open the local claim URL, and create the first administrator. + +## The first 15 minutes + +1. Run the installer on a supported Linux VPS with Docker or permission to install it. +2. Claim the instance through the loopback URL. +3. Keep it private or publish it through the supported Caddy/Cloudflare flow. +4. Confirm the local host was automatically enrolled. +5. Connect one repository-backed Docker Compose application. +6. Record its exact repository, branch, deployed revision, Compose file and public URL. +7. Confirm runtime and public health in GroundControl. +8. Connect ChatGPT or another MCP client through OAuth. +9. Grant one deployment and only the capabilities needed for the trial. +10. Ask the agent to list, inspect and check health before permitting a redeploy. + +## A safe pilot + +Start with one stateless or easily recoverable application. + +Recommended grant: + +- `deployment:read` +- `deployment:health` +- `deployment:logs` +- `operation:read` +- `deployment:redeploy` only after read-only checks succeed + +Do not begin with database mutation, volume deletion, firewall changes, arbitrary terminal access, or production secrets. + +## A useful ChatGPT acceptance conversation + +Use outcome-oriented requests: + +```text +List the deployments available to you. + +Inspect and report its repository, deployed revision, +container health and public endpoint health. + +Redeploy . Return the operation ID, monitor it until +GroundControl finishes verification, and report the evidence. +``` + +Expected behaviour: + +- ChatGPT sees only deployments included in its grant. +- GroundControl—not the model—checks policy and executes typed operations. +- The chat receives an operation ID rather than holding an SSH session open. +- The operation continues if the chat disconnects. +- Final reporting includes runtime and customer-facing verification evidence. + +## Merge-triggered deployment + +Enable this only after the manual redeploy path is proven. + +Required deployment identity: + +- repository +- allowed branch +- exact deployed revision +- repository-owned Compose file +- synchronized environment contract +- public verification URL +- previous known-good artifact or revision +- deployment-specific autopilot policy + +A signed, allowed push creates a durable `deployment.source.deploy` operation. Existing CI or an approved isolated builder produces the artifact; the production VPS is not the default builder. + +## Upgrade safely + +Preview first: + +```bash +curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install \ + | sudo bash -s -- --preview --version latest --json +``` + +Then upgrade: + +```bash +curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install \ + | sudo bash -s -- --upgrade --version latest --json +``` + +The upgrade contract identifies persistent storage, resolves the target image, backs up database and configuration state, starts the digest-pinned image, checks health, and restores the previous state if acceptance fails. + +## Uninstall without deleting data + +```bash +curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install \ + | sudo bash -s -- --uninstall --json +``` + +The default uninstall removes the runtime while preserving the database volume and install directory. + +## Current product state + +### Live + +- Single-tenant self-hosted control plane +- Docker, Compose, proxy, deployment, log, metric and terminal operations +- Agent-assisted install and one-time ownership claim +- MCP/OAuth capability grants +- Scoped deployment inspection, health, logs and durable redeploy +- Secret-safe named configuration checks +- Guarded upgrade with backup, verification and automatic rollback +- Data-preserving uninstall +- Deployment-scoped merge-triggered proof on RentAWeekend + +### Early access + +- Daytona reproduction for eligible code/configuration failures +- Guarded merge-triggered autopilot beyond the proven deployment +- Provider-dependent public publishing paths across varied VPS environments + +## Production checklist + +- [ ] Backups exist outside the VPS. +- [ ] GroundControl binds to loopback unless intentionally published. +- [ ] HTTPS protects any public management endpoint. +- [ ] Every agent grant is deployment- and capability-scoped. +- [ ] Deployed repository revision is recorded. +- [ ] Builds occur away from the production VPS. +- [ ] Health checks cover all declared Compose services. +- [ ] A meaningful public verification URL is configured. +- [ ] A known-good rollback artifact is retained. +- [ ] One harmless redeploy proof has passed. +- [ ] Durable operation evidence is reviewable. + +## Evidence + +- [Clean-host distribution acceptance](./acceptance/distribution-2026-09-21.md) +- [Deployment automation and Daytona](./DEPLOYMENT-AUTOMATION-AND-DAYTONA.md) +- [Agent-assisted distribution](./agent-assisted-distribution.md) diff --git a/docs/LAUNCH-PLAYBOOK.md b/docs/LAUNCH-PLAYBOOK.md new file mode 100644 index 0000000..0d48cc7 --- /dev/null +++ b/docs/LAUNCH-PLAYBOOK.md @@ -0,0 +1,156 @@ +# GroundControl launch playbook + +## Launch position + +**One line:** Give ChatGPT and other approved agents scoped deployment capabilities on infrastructure you own—without sharing SSH keys. + +**Proof:** ChatGPT operated an enrolled production deployment through a scoped OAuth grant, a durable GroundControl operation, and customer-facing verification. Separately, the installer passed fresh-host install, claim, verification, upgrade and data-preserving uninstall acceptance. + +**Primary audience:** founders and lean engineering teams running Docker Compose behind Caddy or Nginx on one to five VPS hosts. + +## Do not lead with + +- “AI-powered VPS dashboard” +- the full feature inventory +- Daytona as a separate product +- unrestricted autonomous infrastructure +- replacement claims for GitHub Actions, Portainer or existing CI + +Lead with the trust boundary and the verified outcome. + +## Proof bundle required before launch + +- [x] Public product page +- [x] Public source repository +- [x] One-command private-first installer +- [x] Redacted clean-host acceptance record +- [x] Real ChatGPT grant, health and redeploy captures +- [x] Verified production deployment evidence +- [x] Adoption guide +- [x] Technical article draft +- [ ] 45–75 second launch video using the real sequence +- [ ] One clean social image +- [ ] Public GitHub release/tag +- [ ] Issue and discussion templates for pilot feedback +- [ ] Three external testers who did not build the product + +## Product Hunt + +### Tagline + +**Infrastructure capabilities for AI agents—without sharing SSH keys** + +### Short description + +GroundControl is a self-hosted control plane that lets ChatGPT and other approved agents inspect deployments, check health and configuration, start durable redeploys, and return verification evidence on infrastructure you own. + +### First comment + +I built GroundControl after repeatedly facing the same uncomfortable choice: either keep an AI agent away from production, or give it credentials and a terminal. + +GroundControl introduces a control plane between the agent and the VPS. The agent receives deployment-scoped, typed capabilities through MCP and OAuth. GroundControl keeps SSH keys and provider credentials, enforces policy, runs durable operations, and verifies the customer-facing result. + +For the production proof, ChatGPT operated RentAWeekend through a scoped grant. A signed merge event created a durable deployment operation; web, API, PostgreSQL and Redis finished healthy, and the public endpoint returned HTTP 200. + +The installer has also passed a disposable clean-host acceptance covering one-time ownership claim, persistent storage, MCP/OAuth discovery, idempotent rerun, backup-backed upgrade and data-preserving uninstall. + +I would especially value feedback from founders and small teams running Docker Compose on VPS infrastructure: what would you need to trust this with one real service? + +### Gallery order + +1. The promise: agent capabilities without SSH keys +2. OAuth grant with exact deployment and capabilities +3. ChatGPT reading live health +4. Durable operation ID and progress +5. Verified public outcome +6. Private-first installation and one-time claim +7. Architecture/trust-boundary diagram +8. Adoption CTA + +## Hacker News + +### Title + +Show HN: GroundControl – let agents operate your VPS without giving them SSH + +### Post + +I built GroundControl, a self-hosted control plane for Docker Compose applications behind Caddy/Nginx. + +Instead of giving an agent a terminal, GroundControl exposes deployment-scoped capabilities through MCP + OAuth: inspect, health, logs, secret-safe configuration presence checks, durable redeploy, and operation evidence. + +The production proof used ChatGPT against one enrolled RentAWeekend deployment. The agent received no SSH key. A signed allowed push became a durable operation; GroundControl completed the deployment and verified web, API, PostgreSQL, Redis and the public endpoint. + +The installer is private-first and has a clean-host acceptance covering one-time claim, persistent storage, MCP/OAuth discovery, idempotent rerun, guarded upgrade and data-preserving uninstall. + +Source: https://github.com/teckedd-code2save/groundcontrol +Product: https://trygroundcontrol.serendepify.com + +I am looking for feedback from people running small VPS fleets: is the typed capability boundary enough for you to let an agent operate one non-critical service? + +## Reddit and communities + +Use the same evidence, but adapt the question: + +- r/selfhosted: focus on single tenancy, private-first installation, data ownership and no shared dashboard. +- r/devops: focus on deterministic policy, durable operations, exact revisions, verification and rollback. +- Docker/Compose communities: focus on preserving repository-owned Compose. +- MCP/agent communities: focus on OAuth grants and constrained tool surfaces. +- Indie Hackers: focus on operating without a dedicated SRE team. + +Do not cross-post identical copy on the same day. Participate in the discussion and publish technical details before asking for adoption. + +## LinkedIn + +### Founder post + +I wanted ChatGPT to help operate my applications—but I did not want to give it an SSH key. + +So I built GroundControl: a self-hosted control plane that gives approved agents scoped deployment capabilities through MCP and OAuth. + +The agent can inspect a selected deployment, check health and configuration, start a durable redeploy, reconnect later, and report verification evidence. GroundControl keeps the credentials and enforces the action boundary. + +We have now proven the path on a real RentAWeekend deployment and passed a fresh-host distribution acceptance covering install, one-time claim, persistent storage, upgrade and data-preserving uninstall. + +The interesting part is not that an AI ran a command. It is that the model never held production authority. + +Try it: https://trygroundcontrol.serendepify.com +Source: https://github.com/teckedd-code2save/groundcontrol + +## Launch order + +1. Recruit three design partners and watch them install without help. +2. Fix the first-run blockers they expose. +3. Publish the technical article and GitHub release. +4. Publish the launch video and LinkedIn proof. +5. Launch on Product Hunt. +6. Submit Show HN after the technical article is live. +7. Share tailored posts with self-hosted, DevOps and MCP communities. +8. Track installs, claims, first enrolled deployment, first health check, first durable operation and verified recovery. + +## Adoption metrics + +Track a small funnel: + +| Stage | Signal | +|---|---| +| Interest | Product-page visit → source/install click | +| Install | Installer returns `claim_required` | +| Ownership | One-time claim completes | +| Activation | First VPS and deployment are enrolled | +| Agent value | OAuth grant completes and first health check runs | +| Operational value | First durable operation reaches verified success | +| Retention | Operator returns or runs another verified operation within 14 days | + +Never collect claim tokens, secret values, raw credentials or customer log contents as launch analytics. + +## Stop conditions + +Delay broad launch if: + +- a fresh install cannot complete without author intervention; +- the latest image and installer checksum disagree; +- one-time claim or private binding regresses; +- upgrades cannot restore a healthy previous state; +- the public site claims features beyond current evidence; +- the first three external pilots cannot reach a verified health check. diff --git a/docs/README.md b/docs/README.md index bb929bb..31dc8c8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,11 @@ ## 🚀 Run it +- **[ADOPTION.md](./ADOPTION.md)** — install privately, run a safe first pilot, connect an agent, enable merge-triggered delivery, and operate upgrades. +- **[acceptance/distribution-2026-09-21.md](./acceptance/distribution-2026-09-21.md)** — redacted evidence from the successful clean-host distribution acceptance. +- **[LAUNCH-PLAYBOOK.md](./LAUNCH-PLAYBOOK.md)** — evidence-led Product Hunt, Show HN, LinkedIn, community, and pilot plan. +- **[articles/chatgpt-operated-my-deployment.md](./articles/chatgpt-operated-my-deployment.md)** — technical article draft explaining the ChatGPT production proof and trust boundary. + - **[../DEPLOY.md](../DEPLOY.md)** — complete production deployment: VPS → domain → Caddy → SSL → first login. - **[DEPLOYMENT-AUTOMATION-AND-DAYTONA.md](./DEPLOYMENT-AUTOMATION-AND-DAYTONA.md)** — the live merge-to-deploy contract, verified RentAWeekend proof, production safety rules, and Daytona's bounded role. - **[agent-assisted-distribution.md](./agent-assisted-distribution.md)** — agent-assisted installation, publishing, verification, upgrades, and clean-host distribution acceptance. diff --git a/docs/acceptance/distribution-2026-09-21.md b/docs/acceptance/distribution-2026-09-21.md new file mode 100644 index 0000000..fdb7857 --- /dev/null +++ b/docs/acceptance/distribution-2026-09-21.md @@ -0,0 +1,45 @@ +# Distribution acceptance — 21 September 2026 + +> Result: passed on a disposable GitHub-hosted Linux machine against GroundControl revision `e27dddec3bdf5944de7ca7317b1bbbf32b203953`. + +This record contains the redacted evidence for the first launch-candidate distribution acceptance run. It proves the installer contract on a clean host; it does not claim that every provider-specific public HTTPS path has been exercised. + +## Run + +- Workflow: [Distribution Acceptance #7](https://github.com/teckedd-code2save/groundcontrol/actions/runs/35617805067) +- Trigger: manual `workflow_dispatch` +- Image selector: `latest` +- Job: `clean-host` +- Result: success +- Evidence artifact: `distribution-acceptance-e27dddec3bdf5944de7ca7317b1bbbf32b203953` +- Artifact digest: `sha256:3d753f54fb31c8abfd314eb840b023c4372516df2944e94df0a5c3e88cfaffa9` + +## What passed + +| Contract | Evidence | +|---|---| +| Installer integrity | Shell syntax and published checksum passed | +| Immutable runtime | Installer resolved `latest` to image digest `sha256:50b1186f7eb95d87eacf71f8cf35172d48c7f6bca8e20d549c173c73f411ff0b` | +| Private-by-default bootstrap | Bound to `127.0.0.1:3003` and returned `claim_required` | +| Container readiness | Docker, container and health checks returned `ready` | +| Human ownership boundary | One-time claim created the first admin; no active claim remained afterward | +| Idempotency | Rerunning the installer returned `already_claimed` with `changed: false` | +| Persistent storage | Database used a persistent Docker volume | +| Host execution | Strict host execution plane returned `ready` | +| PTY | PTY relay returned `ready` with `/bin/sh` | +| Agent discovery | MCP discovery exposed GroundControl deployment tools | +| OAuth discovery | Protected-resource metadata returned `ready` | +| Upgrade preview | Container, storage and target image checks returned `ready` | +| Guarded upgrade | SQLite/Compose state was backed up; the digest-pinned workload returned healthy | +| Session continuity | The claimed operator state survived the upgrade | +| Uninstall | Runtime was removed with `dataPreserved: true` | + +## Deliberate scope + +The acceptance instance stayed private, so `publicHttps` was correctly reported as `skipped`. Direct-domain Caddy and Cloudflare Tunnel publishing remain provider-dependent integration checks and must not be represented as part of this clean-host result. + +## Launch claim this evidence supports + +> GroundControl can be installed on a clean Linux host, claimed by its owner, verified for agent use, safely upgraded with a recoverable backup, rerun idempotently, and uninstalled without deleting its data. + +Do not shorten this to “zero-risk installation” or imply that every VPS distribution, DNS provider, or public publishing path is already proven. diff --git a/docs/articles/chatgpt-operated-my-deployment.md b/docs/articles/chatgpt-operated-my-deployment.md new file mode 100644 index 0000000..45a398d --- /dev/null +++ b/docs/articles/chatgpt-operated-my-deployment.md @@ -0,0 +1,84 @@ +# I gave ChatGPT infrastructure access without giving it SSH + +Most “AI for infrastructure” demos begin by placing a model in front of a terminal. + +That is impressive, but it is also the wrong trust boundary for production. + +I built GroundControl around a narrower idea: an agent should ask for an operational outcome, while a control plane owns credentials, policy, execution, verification and rollback. + +## The test + +I connected ChatGPT to a self-hosted GroundControl instance through MCP and OAuth. The grant exposed only selected deployments and a small set of typed capabilities: + +- inspect deployment identity; +- read health and logs; +- confirm whether named configuration exists without reading its value; +- start a durable redeploy; +- retrieve operation progress and evidence. + +ChatGPT never received the VPS SSH key, provider credentials or unrestricted terminal access. + +I then used RentAWeekend as the production proof. + +ChatGPT inspected the deployment and checked the live runtime. A signed push to the explicitly allowed repository and `main` branch created a durable `deployment.source.deploy` operation inside GroundControl. + +The operation completed in one attempt with no recorded error. Web, API, PostgreSQL and Redis were healthy. The public endpoint returned HTTP 200 at approximately 99 ms during verification. + +That result matters more than “the command ran.” A healthy process is not proof that the customer can reach the application. + +## Why durable operations matter + +A chat request is temporary. Deployment work is not. + +GroundControl returns an operation ID, continues independently of the conversation, records each stage, and lets the agent reconnect later. This avoids holding a shell session open and prevents a disconnected chat from making the state of production ambiguous. + +The model can explain the result, but it does not decide whether it is permitted to mutate the host. That decision belongs to deterministic policy: + +- exact deployment scope; +- typed action; +- allowed repository and branch; +- idempotency; +- execution budget; +- verification; +- rollback or safe abstention. + +## The distribution problem + +The control plane itself also has to be trustworthy to install. + +A fresh-host acceptance run now proves that GroundControl can: + +1. install from one command; +2. bind privately to loopback; +3. return a short-lived one-time claim; +4. create the first human administrator; +5. expose MCP and OAuth discovery; +6. preserve its database on a Docker volume; +7. rerun without changing a healthy installation; +8. preview and perform a backup-backed upgrade; +9. preserve the operator session across that upgrade; +10. uninstall without deleting its data. + +The acceptance ran against revision `e27dddec3bdf5944de7ca7317b1bbbf32b203953` and passed on a disposable Linux host. + +## Where Daytona fits + +Daytona is useful when live evidence points to a repository, configuration or Compose defect that needs isolated reproduction. It is not the production runtime and it is not required for every incident. + +The intended path is: reproduce the exact deployed revision in an ephemeral sandbox, validate the smallest candidate fix, open a normal pull request after approval, let the existing delivery pipeline deploy it, and let GroundControl verify the public outcome. + +## What GroundControl is—and is not + +GroundControl is a self-hosted operational control plane for applications running on infrastructure you own. It builds on Docker Compose, Caddy or Nginx, GitHub Actions and registries. + +It is not a new CI provider, an unrestricted shell agent, or a replacement for the tools already delivering your software. + +The useful product boundary is simple: + +> Give agents infrastructure capabilities, not infrastructure credentials. + +GroundControl is open source. You can install it privately, connect one deployment, and test the same read → operate → verify loop. + +- Product: https://trygroundcontrol.serendepify.com +- Source: https://github.com/teckedd-code2save/groundcontrol +- Adoption guide: https://github.com/teckedd-code2save/groundcontrol/blob/main/docs/ADOPTION.md