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; the core container 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.

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.

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 and application defaults.

These files contain configuration, not credentials. Keep provider configuration declarative: Pi management rejects executable !command values. Do not edit generated files, the running container, or a host-native Pi directory.

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

"$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. Do not delete .thothctl, state files, containers, or volumes. Inspect status and sanitized logs, then restore the previous image when an update is involved:

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

Repair the reported Docker, disk, or configuration problem, then have ThothII complete the 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. Do not run package installers, alter files inside the live container, mount the Docker socket, expose a browser shell, or use a host Pi as a substitute.

6.1 KiB Raw Blame History