ThothII/docs/install/local-workspace-registry.md

Local workspace repository installation (macOS, Windows, and Linux)

This manual connects a local ThothII installation to one remote Git repository hosted by a Git server such as GitHub, GitLab, or Gitea. ThothII is a read-only consumer: it fetches, validates, and activates workspace revisions, but never edits, commits, pushes, or publishes them.

Architecture ownership contract

Component	Ownership	Operator contract
DWH	External	Configure the external endpoint and complete its runtime credentials in Workspace management.
LLM	External	Configure the external endpoint and model policy during installation.
Qdrant	Internal	Compose runs the internal service and persists qdrant-data.
Ollama embedding	Internal	Compose runs the internal qwen3-embedding:0.6b service and model-init job.

Semantic index ownership contract

Scope	Ownership rule	Isolation rule
Workspace semantic index	Each workspace keeps exactly one Qdrant collection reserved for itself.	Schema, Evidence, and memory records share that one collection and are separated by the kind payload.

The mandatory semantic stack is CPU-first. Set THOTH_ENABLE_EMBEDDING_GPU=1 only after the documented GPU prerequisites are satisfied. The embedding contract is fixed at qwen3-embedding:0.6b, 1024 dimensions, cosine distance.

Prerequisites

• A working local installation described by local.md.
• A remote Git repository and a read-only deploy credential for this ThothII installation.
• A separate authoring clone in which a workspace curator can edit and publish source revisions.
• tht built with bash scripts/build-tht.sh.

Prepare and publish a workspace source

Create a local workspace in an ordinary source directory outside ThothII's data directories. The canonical repository layout is:

thoth-workspaces.yaml
<workspace-id>/workspace.yaml
<workspace-id>/evidence/                 # optional, repository-owned Evidence
<workspace-id>/schema/annotations.yaml   # optional curated annotations

The catalog lists {id, name, description?} and the descriptor at <workspace-id>/workspace.yaml must match that metadata. Use the examples in deploy/workspaces/ as authoring references. Do not store passwords, tokens, private keys, or signed URLs in Git.

Publishing is an author-side Git operation: validate the source, commit it, and push it from the separate authoring clone to the configured branch. This is the only meaning of “publish” in the workspace lifecycle. ThothII has no author identity and no Git write credential.

Use the workspace from the application

After the installation is started, use Workspace management from the authenticated application:

1. Run Update workspace repository to fetch and validate the configured Git branch into the application-owned registry. The operation is all-or-nothing and does not modify the authoring clone.
2. Confirm that the installation-owned workspace-secrets storage remains outside the source repository and contains no credentials in the workspace descriptors.
3. Select the workspace and run Validate workspace to verify the active descriptor, catalog, Evidence, annotations, and runtime bindings.
4. Run Test connections only with the approved read-only DWH/Evidence test configuration. Results are redacted and the workspace source remains unchanged.

Schema v3 is the only accepted workspace descriptor. Schema v1 and v2 workspace descriptors are rejected before activation.

Configure the remote Git repository

Copy docs/install/examples/thothii-installation.local.yaml to an operator-controlled absolute path. Its workspaceRepository block records the remote, branch, and read-only access method. Choose exactly one transport override:

• SSH: deploy/compose.git-ssh.yaml, with a read-only deploy key and pinned known_hosts file.
• HTTPS: deploy/compose.git-https.yaml, with a read-only token in a Git credentials file and an optional private CA file.

The remote and branch are installation configuration. Git credentials remain protected installation files and are never accepted by Workspace management or returned by its API.

Example non-secret/operator paths:

THT_WORKSPACE_GIT_REMOTE=git@git.example.com:organization/workspaces.git
THT_WORKSPACE_GIT_BRANCH=main
THT_WORKSPACE_INSTALLATION_ID=local
PI_AUTH_FILE=/absolute/path/to/operator/pi-auth.json
THT_SECRETS_FILE=/absolute/path/to/operator/thothii.secrets
THT_WORKSPACE_GIT_SSH_KEY_FILE=/absolute/path/to/operator/git-ssh-key
THT_WORKSPACE_GIT_KNOWN_HOSTS_FILE=/absolute/path/to/operator/git-known-hosts

Keep these files outside both the ThothII checkout and the workspace source repository. Protect them with mode 0600 on macOS/Linux or an equivalent single-user ACL on Windows.

Start and update the installation

Use only the installation-aware lifecycle:

export THT_SOURCE_ROOT=/absolute/path/to/ThothII
THT_BIN=tht
INSTALLATION=/absolute/path/to/operator/thothii-installation.yaml
"$THT_BIN" --installation "$INSTALLATION" start
"$THT_BIN" --installation "$INSTALLATION" doctor

At startup ThothII clones or fetches the configured repository into its application-managed workspace-registry volume. Later, Update workspace repository performs a server-side fetch and fast-forward candidate checkout. It does not copy anything to the user's computer.

Complete runtime secrets in Workspace management

Open Workspace management after the first successful repository update.

1. At the repository level, review the configured host, repository, branch, and current revision.
2. Select a workspace. Repository update does not require a selection; validation and connection tests do.
3. Review the runtime fields derived from the selected DWH transport and Evidence authentication mechanism.
4. Enter or rotate the required values and choose Save runtime secrets.
5. Run Validate workspace and then Test connections.

Secret fields are write-only. The GUI receives only configured/missing status. Values are encrypted by the backend in the platform-neutral workspace-secrets volume. ThothII temporarily materializes a restrictive file only while an existing file-oriented connector needs it, then removes that file when the runtime lease ends. Forget deletes the selected encrypted value.

The workspace YAML stays environment-independent: it declares connector mechanisms, not host paths or credentials. Installation trust material such as a Git CA or known_hosts remains an operator concern; DWH and Evidence credentials are completed in the GUI.

Validation and activation behavior

An update follows this sequence:

1. Fetch the configured branch into a candidate checkout managed by ThothII.
2. Validate the catalog, every descriptor, repository-relative Evidence, and cross-workspace invariants at the same Git commit.
3. If every workspace is valid, atomically mark that complete commit as active.
4. If any validation fails, report sanitized diagnostics and keep the previous active revision.

The active checkout is read-only application state. Never edit files under /data/workspace-registry. A source correction must be committed and pushed from the authoring clone, then fetched again with Update workspace repository.

Backup, rotation, and recovery

Back up the workspace-registry, workspace-secrets, sessions, qdrant-data, embedding-models, settings, and pi-state volumes together. The encrypted vault is useless without its generated master key, so preserve the entire workspace-secrets volume and protect the backup as secret material.

Rotate a runtime credential by saving its replacement in Workspace management and rerunning its connection test. Rotate Git credentials in the installation files and restart core. To recover from a bad remote revision, correct or revert it in the authoring repository and run the update; until validation succeeds, the previous active snapshot remains available.

Troubleshooting

Symptom	Meaning and action
Repository unavailable	Check remote host, branch, read-only deploy credential, CA, and known_hosts.
Candidate rejected	Fix the reported source error in the authoring clone, commit, push, and update again.
Runtime configuration required	Select the workspace and complete each required secret field.
Connection test fails	Rotate the relevant secret or correct the non-secret endpoint in the source/installation as appropriate.
Active revision did not change	The candidate was invalid or was already active; inspect the repository status.