# Pi management ThothII bundles Pi in the `core` image. Operators use the Pi Management page for safe application defaults and the host-side `thothctl` CLI for lifecycle work. A local Pi installation is not required. In the commands below, replace `/absolute/path/to/thothii-installation.yaml` with the protected installation descriptor created by the [local installation guide](local.md). ```sh THTCTL=/absolute/path/to/thothctl INSTALLATION=/absolute/path/to/thothii-installation.yaml ``` ## Choose application defaults Use the **Pi Management** page to select the supported provider, model, and reasoning default, then choose **Save defaults**. The page shows credentials only as present or missing and can run bounded diagnostics; it never accepts or displays a credential, opens a terminal, or updates an image. Alternatively, use the CLI from an administrator terminal: ```sh "$THTCTL" --installation "$INSTALLATION" pi configure "$THTCTL" --installation "$INSTALLATION" pi configure --provider zai --model glm-5.2 --thinking medium ``` Use GUI Save defaults or CLI `pi configure`, not both for the same change. The CLI's interactive choices are restricted to supported models; non-interactive use must supply all three values. Both methods store application defaults in backend installation settings, not in the project policy file. Useful read-only checks are: ```sh "$THTCTL" --installation "$INSTALLATION" pi status "$THTCTL" --installation "$INSTALLATION" pi doctor "$THTCTL" --installation "$INSTALLATION" pi test "$THTCTL" --installation "$INSTALLATION" pi check "$THTCTL" --installation "$INSTALLATION" pi logs ``` `pi check` is an alias for `pi test`; logs are a sanitized, bounded snapshot with no follow mode. ## Edit the provider catalog and enabled-model policy Edit these project-root files in source control, then review and deploy the change through the normal project process: - `deploy/pi/models.json` is the provider catalog: provider endpoints and the models each provider offers. - `deploy/pi/settings.json` is the enabled-model policy only; it lists the models available to the application and does not store application defaults. These files contain configuration, not credentials. Keep provider configuration declarative: Pi management rejects executable `!command` values. Docker Compose mounts the selected configuration and credential files read-only. ## Store provider credentials `PI_AUTH_FILE` is a setting in the installation environment file (for example, `deploy/env/local.env`). Its value is the absolute path of the protected host credential file that this installation selects. Docker Compose mounts that selected file read-only for Pi. Other declared protected material is likewise mounted read-only under `/run/secrets`. Set restrictive permissions on the host file (`0600` on macOS/Linux or a user-only ACL on Windows). Never put its contents in installation YAML, Git, command arguments, the browser, screenshots, tickets, rendered Compose output, or logs. Do not print the file while troubleshooting. ## Reload changed configuration After changing the provider catalog, enabled-model policy, or selected credential file, reload the running application with one confirmed restart: ```sh "$THTCTL" --installation "$INSTALLATION" pi restart --yes --drain ``` `--yes` confirms that core will be recreated. Without `--drain`, restart refuses active sessions; with it, ThothII closes admission and waits for active sessions to finish without terminating them. The wait is bounded. Restart retains the current image: it does not build, pull, select, or upgrade an image. It will restart only core, then verifies health, Pi version, settings/model smoke, non-secret rendered configuration, and persistence mounts before reopening admission. Use `pi restart --yes` when there are already no active sessions. Do not substitute `thothctl stop` and `thothctl start` or raw Compose commands for this reload workflow. ## Update the bundled Pi version `pi update` is for a new bundled Pi version; it is not a configuration reload. Finish or drain active work, then choose an explicit source and version. A build update uses this checkout: ```sh "$THTCTL" --installation "$INSTALLATION" pi update \ --version 0.81.0 --source build --yes --drain ``` A registry update must use an immutable digest, never a mutable tag: ```sh "$THTCTL" --installation "$INSTALLATION" pi update \ --version 0.81.0 --source pull \ --image registry.example.invalid/thothii-core@sha256:<64-lowercase-hex-digits> \ --yes --drain ``` Update keeps new-session admission gated while it builds or pulls a candidate, recreates only `core`, verifies it, and promotes the image only after success. It preserves the frontend and named volumes. ## Recover a failed lifecycle operation If a restart or update fails after core recreation, leave maintenance enabled and preserve the reported recovery state. Do not delete `.thothctl`, state files, containers, or volumes. Inspect status and sanitized logs: ```sh "$THTCTL" --installation "$INSTALLATION" pi maintenance status "$THTCTL" --installation "$INSTALLATION" pi status "$THTCTL" --installation "$INSTALLATION" pi logs ``` For a failed update, restore its prior image: ```sh "$THTCTL" --installation "$INSTALLATION" pi rollback --yes ``` For a failed restart, use maintenance recovery instead of rollback. After repairing the reported Docker, disk, or configuration problem, use the same command to complete either safe recovery path: ```sh "$THTCTL" --installation "$INSTALLATION" pi maintenance recover --yes "$THTCTL" --installation "$INSTALLATION" pi doctor "$THTCTL" --installation "$INSTALLATION" pi test ``` `pi rollback --yes` restores the prior update image. `pi maintenance recover --yes` checks both restart and update recovery state before it can reopen admission. If either command fails, keep the installation gated and collect only the sanitized diagnostics. ## Direct support access Raw Compose access is unsupported because it can bypass the installation-specific environment and durable image selector. For support, use the installation-aware `thothctl pi status`, `thothctl pi doctor`, `thothctl pi test`, and `thothctl pi logs` commands.