# Pi management Pi is pinned inside the ThothII `core` image. A local Pi, Node.js, Python, or Go installation is not required. The browser can manage safe runtime settings, while the host-side `thothctl` operator CLI performs container lifecycle and image updates. The core does not mount the Docker socket, and there is no browser shell. In the commands below, replace `/absolute/path/to/thothii-installation.yaml` with the protected installation descriptor created by the [local installation guide](local.md). ## Who can use Pi Management On the loopback-only local profile (`AUTH_MODE=none`), the person using that PC can open Pi Management and change installation defaults or run diagnostics. Do not expose ports 8080 or 8787 to another machine. On a public server, Pi Management requires upstream authentication and a trusted administrator claim supplied by the authenticated reverse proxy. Without that claim the API returns `403 pi_management_forbidden`; ordinary users cannot change installation-wide Pi settings. Image updates are never available from the web page on either profile. ## Use the Pi Management page Open ThothII, choose **Pi Management**, and check the bundled version and readiness. The page: - offers only supported provider, model, and reasoning choices; - saves non-secret defaults; - reports credentials only as present or missing; - runs a bounded provider smoke test; and - shows at most 200 sanitized log lines. It never displays or accepts a credential, runs an image update, or opens a terminal. Per-user browser preferences remain separate from installation defaults. ## Use thothctl Set a short shell variable for the platform-specific executable. Examples below use macOS/Linux: ```sh THTCTL=/absolute/path/to/thothctl INSTALLATION=/absolute/path/to/thothii-installation.yaml ``` The complete Pi command set is: ```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 configure "$THTCTL" --installation "$INSTALLATION" pi configure --provider zai --model glm-5.2 --thinking medium "$THTCTL" --installation "$INSTALLATION" pi logs "$THTCTL" --installation "$INSTALLATION" pi maintenance status ``` - `pi status` reads the image-bundled version. - `pi doctor` checks the version boundaries, core health, settings, and configured model. - `pi test` runs the isolated Pi/core smoke; `pi check` is its alias. - `pi configure` presents closed choices on a terminal. Non-interactive use requires all three flags. Never pass a credential as an argument. - `pi logs` returns a bounded, sanitized snapshot and deliberately has no follow mode. - `pi maintenance status` reports whether new session admission is gated. Use `thothctl status`, `doctor`, `logs`, `start`, `stop`, and `update --check-only` for the wider installation. Direct Compose lifecycle commands can bypass the durable image selector and are not the normal operator interface. ## Handle credentials and secrets Keep provider credentials in the protected host file named by `PI_AUTH_FILE`, or in the documented model secret file/bundle. Compose mounts protected material read-only under `/run/secrets` or at Pi's protected auth path. Apply mode `0600` on macOS/Linux or a user-only ACL on Windows. Never put secret text in the installation YAML, operator environment, workspace Git repository, command arguments, browser, screenshots, tickets, rendered Compose, or logs. Pi configuration is declarative: executable `!command` values are rejected. Use supported environment references or the protected credential files. After rotating a credential, restart core through `thothctl stop` and `thothctl start`, then run `pi doctor` and `pi test`. Do not print the file while troubleshooting. ## Update and roll back Pi Finish or close active work first. A build update uses source already present in 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 ``` The operation gates new sessions, records non-secret recovery state, recreates only `core`, checks the requested version, health, settings, smoke request, configuration, and persistence mounts, then promotes the verified image. Frontend and named volumes are preserved. To restore the image recorded by the interrupted or latest update: ```sh "$THTCTL" --installation "$INSTALLATION" pi rollback --yes ``` ## Recover a failed update Do not delete `.thothctl`, `update-state.json`, `current-image.yaml`, containers, or volumes. First inspect the durable gate and sanitized logs: ```sh "$THTCTL" --installation "$INSTALLATION" pi maintenance status "$THTCTL" --installation "$INSTALLATION" pi logs "$THTCTL" --installation "$INSTALLATION" pi rollback --yes ``` If rollback reports a terminal or stale maintenance state, repair the reported Docker, disk, or configuration problem, then run: ```sh "$THTCTL" --installation "$INSTALLATION" pi maintenance recover --yes "$THTCTL" --installation "$INSTALLATION" pi doctor "$THTCTL" --installation "$INSTALLATION" pi test ``` If recovery still fails, leave maintenance active and preserve the recovery file. Collect only sanitized `pi logs`, `status`, and `doctor` output for support; do not ungate the installation by editing state files. ## Direct support access Raw Compose access is unsupported: there is no public operator command that safely reconstructs the installation's hashed project name, project directory, environment file, optional overrides, and durable current-image selector for ad-hoc Pi execution. Do not approximate those arguments or delete/edit lifecycle state for support. Route direct executable/version checks through `thothctl pi status`, and collect diagnostics with `thothctl pi doctor`, `thothctl pi test`, and `thothctl pi logs`. These commands are installation-aware and redact declared secret values. Share only their sanitized output. Do not run package installers, alter Pi files inside the live container, mount the Docker socket, expose a browser shell, or use a host Pi as a substitute.