Distribution: agent-assisted install, claim, and first connection

[teckedd-code2save]

Product goal

Installing GroundControl should be agent-native too.

A developer should be able to tell an authorized coding/ops agent:

Install GroundControl on this VPS and connect it to my agent.

The agent may do the mechanical work, but GroundControl must preserve a safe human claim/approval boundary for privileged access.

North-star flow

1. User gives an agent legitimate access to a VPS it controls.
2. Agent checks prerequisites and host compatibility.
3. Agent installs GroundControl using a stable, documented installer.
4. GC starts locally and reports a one-time claim URL/code.
5. Human claims the instance and creates/links the administrator identity.
6. Agent may continue setup only within the permissions granted after claim.
7. GC establishes/validates its public HTTPS endpoint or supported outbound bridge.
8. User connects ChatGPT/another MCP client through OAuth.
9. GC runs post-install verification:
   • container healthy
   • persistent DB volume
   • Docker host execution plane
   • terminal PTY
   • MCP discovery
   • OAuth metadata
   • no default/shared credentials
10. Agent returns evidence and next capabilities instead of a pile of shell logs.

Installer requirements

• one canonical install surface, versioned and checksum-verifiable
• idempotent install/upgrade
• explicit supported OS/runtime matrix
• safe Docker/Compose detection
• never transmit SSH keys to GroundControl
• secrets generated on-host
• no permanent bootstrap credential
• rollback/uninstall path
• structured machine-readable output for agents
• human-readable output for manual installs

Suggested commands should support both:

curl ... | sh

and a safer download/verify/run path that agents should prefer.

Claim protocol

Fresh installations should start unclaimed.

Bootstrap may expose only:

• instance identity
• health
• one-time claim initiation
• expiry/revocation of claim tokens

Before claim it must NOT expose:

• terminal
• deployment mutation
• connectors
• secrets
• MCP write capabilities

Claim tokens:

• short-lived
• single-use
• stored hashed
• invalidated after first admin claim
• bind to the exact instance

Agent install contract

Provide structured install stages such as:

{
  "instanceId": "...",
  "stage": "claim_required",
  "publicUrl": "...",
  "checks": {
    "docker": "ready",
    "storage": "ready",
    "hostExecution": "ready",
    "publicHttps": "ready"
  }
}

The installer should give agents deterministic recovery instructions per failed check.

Public networking

Support:

• existing HTTPS/reverse proxy
• automated Caddy path where appropriate
• Cloudflare Tunnel/bridge path for private instances

Do not require a globally open management port.

Upgrade path

Distribution must support:

• pinned releases, not only latest
• upgrade preview/check
• DB migration safety
• health verification
• rollback to previous image when startup verification fails

Acceptance test

From a clean supported VPS:

1. authorized agent installs GC without manual file editing
2. GC boots unclaimed
3. human completes one claim action
4. agent resumes
5. host/terminal/MCP/OAuth checks pass
6. ChatGPT connects to the fresh instance
7. ChatGPT can list an explicitly granted deployment
8. no bootstrap credential survives

This track begins after connector rebuild #86 reaches live acceptance.

[teckedd-code2save]

Distribution/product split update (2026-09-19):

Clarified desired first-install experience:

1. Agent/operator runs canonical scripts/install on the authorized VPS.
2. Installer returns explicit localUrl + full one-time claimUrl in JSON mode.
3. Human claims ownership and creates first admin.
4. GC asks how this instance should be reached:
   • user has a domain -> attach domain, configure supported DNS/reverse proxy, issue/verify HTTPS
   • no domain -> keep private or use a supported outbound HTTPS bridge/tunnel
5. GC returns the resulting publicUrl/management URL.
6. Post-install verification checks host execution, PTY, MCP discovery, OAuth metadata, persistent DB and HTTPS reachability.
7. User connects ChatGPT/other MCP agent through scoped OAuth.

Important boundary: do not make the post-claim operator login a bare public HTTP endpoint. Plain HTTP is local/claim/bootstrap only; public management should be HTTPS.

Also landed product split:

• public marketing/install site lives at trygroundcontrol.serendepify.com
• each GC instance owns its own private/login plane
• public site no longer links visitors into the operator's current single-tenant instance
• operator login is now intentionally small/instance-centric rather than a marketing homepage

Next #93 slice should implement domain/HTTPS + outbound bridge/publicUrl + post-install verification, using this contract.