Skip to content

docs: publish distribution proof and adoption launch kit #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
teckedd-code2save merged 5 commits into from
Sep 21, 2026
Merged

docs: publish distribution proof and adoption launch kit #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
33e8b00
docs: record clean-host distribution acceptance
teckedd-code2save Sep 21, 2026
e0204f5
docs: add GroundControl adoption guide
teckedd-code2save Sep 21, 2026
83ef7ae
docs: add ChatGPT deployment proof article
teckedd-code2save Sep 21, 2026
25c8d5e
docs: add adoption launch playbook
teckedd-code2save Sep 21, 2026
35b9273
docs: index adoption and launch material
teckedd-code2save Sep 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 158 additions & 0 deletions docs/ADOPTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <deployment> and report its repository, deployed revision,
container health and public endpoint health.

Redeploy <deployment>. 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)
156 changes: 156 additions & 0 deletions docs/LAUNCH-PLAYBOOK.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
45 changes: 45 additions & 0 deletions docs/acceptance/distribution-2026-09-21.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading