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.

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:

THTCTL=/absolute/path/to/thothctl
INSTALLATION=/absolute/path/to/thothii-installation.yaml

The complete Pi command set is:

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

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

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:

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

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

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

6.3 KiB Raw Blame History