Maintain your instance
Upgrade, recover and uninstall
Use the same installer for maintenance, with an explicit preview and a database/configuration backup before upgrade.
A verified version change, or an explicitly reported recovery to the previous version.
On this page
1. Preview the target version
This maintenance flow is for the canonical Linux server installation. Rerunning the computer launcher reconnects; it does not upgrade an existing desktop instance. Keep the desktop configuration folder and database volume together.
Run this on the VPS that already hosts GroundControl. Replace YOUR_TAG with the published version or image tag you want. Use the same --dir and --port options if your original install used custom values.
curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install \
| sudo bash -s -- --preview --version YOUR_TAG --jsonThe preview checks the container, persistent storage and target image without replacing the instance.
Current image, storage and target-image checks are ready. If persistent storage cannot be identified, resolve that before upgrading.
2. Apply the guarded upgrade
curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install \
| sudo bash -s -- --upgrade --version YOUR_TAG --jsonThe installer briefly stops GroundControl for a consistent SQLite and configuration backup, resolves the new image, starts it, and checks container health. Backups live under the installation directory’s backups/ folder. The default is /opt/groundcontrol/backups/.
| Returned stage | Meaning |
|---|---|
| upgrade_complete | Requested version passed startup/health verification. |
| upgrade_rolled_back | New version failed; previous database/image/configuration were restored and healthy. The command exits nonzero because the upgrade failed. |
| rollback_failed | Both upgrade and recovery failed. Preserve the backup and failed-upgrade log for manual recovery. |
3. Confirm from outside the container
Open your public instance URL and sign in. Confirm the enrolled deployments and agent grant are present. Ask your agent for a new health check. A successful startup gate is necessary, but it is not a substitute for checking your publishing route and plugin connection.
Keep off-host backups appropriate to your deployment. An installer backup on the same VPS cannot recover from loss of that VPS.
4. Remove the runtime while preserving data
Use this only when you intend to stop this GroundControl instance. It removes the runtime and preserves the database volume and installation files for recovery.
curl -fsSL https://raw.githubusercontent.com/teckedd-code2save/groundcontrol/main/scripts/install | sudo bash -s -- --uninstall --jsonThe result reports dataPreserved: true. Keep the saved data and files until you have verified your recovery or migration. The default path does not delete application data volumes.
What the clean-host test covers
The distribution acceptance run passed install, claim, loopback binding, host execution, PTY, MCP/OAuth discovery, idempotent rerun, a guarded same-image upgrade and data-preserving uninstall. It does not prove an arbitrary cross-version migration, a failed-upgrade rollback or every public publishing provider.
Read the acceptance evidence for exact scope and the original run.