Find the next check
Find the failed boundary
Start with the symptom you actually see. Each check below narrows the problem without blindly repeating a deployment.
A concrete next check for installation, connection, authorization or verification errors.
On this page
The claim page will not open
Confirm the SSH tunnel is running on your computer and the installer’s remote port is correct. On the VPS, inspect container health and read the last startup logs:
docker ps --filter name=groundcontrol-web\ndocker logs --tail 100 groundcontrol-webIf the page opens but the claim expired, rerun the installer on the unclaimed instance. If the instance is already claimed, use its login rather than trying to establish another first owner.
The custom plugin option is missing
Use ChatGPT on the web. Check Settings → Security and login → Developer mode and your workspace’s policy for custom connections. Older interfaces may use Apps or Connectors. The GroundControl installer cannot enable a ChatGPT account feature. See the current OpenAI setup reference.
ChatGPT cannot connect or discovery fails
- Check the URL is the HTTPS origin of your own instance plus
/mcp. - Open the two metadata URLs. Expect JSON with the same public issuer.
- Check the proxy forwards MCP requests and does not replace responses with a sign-in page.
- Use a stable hostname. A changed temporary tunnel URL means the old connection points to the wrong server.
A 401 from a protected endpoint can be expected before OAuth. A repeated 401 after consent calls for reconnection or token diagnosis, not disabling authentication.
No deployments appear, or a tool is missing
| Symptom | Next check |
|---|---|
| Empty list | Is the workload enrolled, and did consent select it? |
| Another workload is invisible | That is expected if it was not included in this grant. |
| 403 for a mutation | Check the granted capability and workload scope, plus management/policy readiness. |
| A new tool is absent | Refresh the connection metadata in ChatGPT and start a new conversation. |
| Only five capabilities at consent | Scopes and tools are different: one read scope can authorize both list and inspect. |
Open GroundControl → Agents to see the active client’s actual scopes and workload slugs. For more access, deliberately reauthorize the intended scope rather than assuming a broad grant.
The connection asks for authentication again
A revoked grant, expired session or missing refresh token can require sign-in again. Use the client’s reconnect action and complete the same OAuth consent flow. offline_access is needed for refresh access; not every client requests it.
The streamlined path avoids giving ChatGPT infrastructure credentials. It does not bypass workspace approval policies or client prompts for write actions.
A redeploy timed out
Read the operation ID already returned by GroundControl before starting another request. Inspect Deploy → View evidence and actual runtime. Work can continue after the caller disconnects.
Check operation OPERATION_ID. If it is still running or verifying, keep following it. If it is uncertain or failed, report its evidence and current deployment health. Do not queue another redeploy.Inspect CPU, memory and disk pressure if the host itself is unresponsive. The RentAWeekend investigation found heavy builds competing with production workloads. Move or schedule build work appropriately; retries can make contention worse.
Containers are running but the public check fails
Read the failed URL, HTTP status and phase. Check application readiness, the proxy upstream, domain/DNS and configured release checks. An HTTP 502 is a failed customer outcome even when the web container is “running.”
Use a known-good artifact and the deployment’s recovery procedure if the release cannot pass. Do not report an automatic application rollback unless the operation actually records that it happened.