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.

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:

"$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:

"$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:

"$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 exact captured running image: it does not build, pull, or upgrade an image. Before recreating core, it pins that image through transaction-scoped Compose override material so a configured tag moving during the operation cannot change the selected image, and Compose is explicitly told never to build or pull. 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:

"$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:

"$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 and transaction override. Do not delete .thothctl, state files, containers, or volumes. Inspect status and sanitized logs:

"$THTCTL" --installation "$INSTALLATION" pi maintenance status
"$THTCTL" --installation "$INSTALLATION" pi status
"$THTCTL" --installation "$INSTALLATION" pi logs

For a failed update, restore its prior image:

"$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:

"$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.

6.4 KiB Raw Blame History