Start with what you can see

Installation stopped

First run docker version and docker compose version in the same environment where the installation command runs. If shimpz is already installed, run shimpz status to inspect the current Space. If either Docker command fails, repair Docker before running the installation command again. Use the check for Linux, macOS, or Windows with WSL2.

If both Docker commands succeed but Shimpz reports Docker or a required host tool as unavailable or refused, reacquire the current release-bound CLI before retrying. Run the installation command again from an interactive terminal. The bootstrap verifies the CLI before it reconciles the Space.

If Docker works and shimpz install reports that its existing Local Space failed runtime validation, read the listed deletion scope. Answer Yes only when you intend to erase that complete Local Space and install a fresh one. Answer No or press Enter to leave every local resource unchanged. Continue with Maintain your Space for the full recovery and reset boundaries.

Admin does not open

Use the exact Admin address printed by shimpz install; do not assume the port is 7777. Compare the visible result with the final step for Linux, macOS, or Windows with WSL2.

The Team does not reply

Send one message that does not require an Assistant. If Shimpz still asks for model configuration, return to Verify the Team can reply and check the selected model and provider key.

The Assistant is missing or authorization did not open

Confirm that the Assistant is installed in the exact Team shown in Chat. If an authorization window was expected, allow pop-ups for Local Admin and retry the message once. Continue with the visible Assistant checks.

The provider identity is wrong

Disconnect that Integration before authorizing the intended provider identity. Use Disconnect before uninstalling to remove access deliberately.

The provider tab shows Bad Gateway

No provider grant was created. Close the provider tab and follow the fail-closed recovery under Bad Gateway means authorization did not start.

An update failed or rolled back

Read the error printed by shimpz update, shimpz start, or shimpz install before retrying. If the candidate failed admission, the installed release was not replaced and the next update checks the same release again. If the replacement did not become healthy, Shimpz attempted to restore the previous working version and remembers the failed release, so later updates wait for a different release. The error states whether the previous release was restored or the rollback also failed. Fix the reported cause, then return to Maintain your Space.

The Supervisor authentication record requires recovery

If an update says that the selected release cannot use the existing Supervisor authentication record, the candidate was refused before its runtime replaced the existing Space. For an existing healthy Space, the installed release is unchanged: a running Space stays available and an intentionally stopped Space stays stopped. The current pre-production recovery is shimpz reset --hard followed by shimpz install; there is no record migration or fallback. The hard reset is authorized by the host, not by the Supervisor: it never contacts Admin or Team, always asks on the interactive terminal, lists the exact Shimpz-owned scope it will delete, and continues only when you type Yes. Docker and operating-system permissions still apply. It permanently deletes the complete managed Local Space and keeps the shimpz command, its lifecycle lock, pulled images, and Creator credentials. Read the deletion scope under Reset only when you want to delete everything first.

You want to remove access or delete Local data

Disconnect provider Integrations and uninstall the affected Assistant when that is enough. Use reset only when you intend to delete every managed Team, Assistant, Integration, setting, conversation, and local Shimpz data.