Installation

GigaLoom 0.7 is the first stable Native Agent Gateway release and builds on the 0.6 breaking clean cut. It supports Python 3.11–3.14. Install at least one provider-native CLI separately and complete that provider's own authentication flow.

Managed provider terminals additionally require a POSIX host and a discoverable tmux whose tmux -V output can be probed. Install tmux with the operating system package manager on Linux or macOS. Windows and POSIX systems without a usable tmux retain provider-native passthrough; GigaLoom does not substitute an emulated terminal UI.

Install GigaLoom

With uv:

uv tool install 'gigaloom==0.9.1'

Or in an isolated Python environment:

python -m pip install 'gigaloom==0.9.1'

Confirm the installed artifact:

giga --version
giga doctor

doctor reports capability and configuration status without reading prompt content or contacting providers.

Upgrade to 0.8

An exact uv tool install constraint remains pinned during uv tool upgrade. To move an existing prerelease installation to 0.8, recreate the tool environment with the new exact requirement:

uv tool install --force 'gigaloom==0.9.1'

If the optional gateway extra was previously installed, retain it explicitly:

uv tool install --force 'gigaloom[gpt2giga]==0.9.1'

Before upgrading, stop every GigaLoom process and back up ~/.gigaloom, the historical ~/.gpt2giga/harness root when it exists, and the .giga/ directory of each registered project.

Namespace and command migration

The PyPI project name changed before the first standalone target release. Remove the historical distribution and install gigaloom; do not delete the existing state directories:

uv tool uninstall gpt2giga-harness
uv tool install 'gigaloom==0.9.1'

Update extensions, imports, scripts, and frontend consumers as one clean cut:

Historical surface	0.6 surface
PyPI gpt2giga-harness	PyPI gigaloom
Python gpt2giga_harness.*	Python gigaloom.*
command gpt2giga-harness	command giga
entry-point group gpt2giga.harnesses	gigaloom.harness_adapters.v1
npm @gpt2giga/harness-cockpit-v2	npm @gigaloom/web
top-level UI aliases such as /work and /workflows	canonical /web/** routes

External adapters must be republished against the new entry-point group; there is no runtime bridge for the old group. The standalone distribution exposes no legacy Python namespace, command, entry-point group, npm package, or Web route alias.

Migrate local state

Before the first 0.6 startup, stop existing Harness processes, unset the removed GPT2GIGA_HARNESS_DATA_DIR override, and run:

giga state migrate --json

The same preflight runs automatically before normal commands that use the default root. Old-only state is backed up under ~/.gigaloom-migration, staged, verified, and atomically promoted to ~/.gigaloom. The legacy root and every project .giga/ remain untouched. If both roots already exist without a completed migration journal, GigaLoom stops and prints explicit mv commands; it never guesses which root is authoritative. Use giga state rollback to restore the verified backup to the legacy root while preserving ~/.gigaloom for diagnosis.

Set GIGALOOM_DATA_DIR to use a custom canonical root. A custom root does not trigger migration of the two default roots.

Upgrade 0.6 state for the Native Agent Gateway

The 0.6→0.7 state change is a separate explicit offline migration. Stop the Web server, workers, native sessions, and every other process using the data directory, then choose a backup path outside that directory:

giga state upgrade --backup ../gigaloom-before-0.7.zip --json

The command first creates and verifies the complete state archive. It then runs the fixed project_catalog_v1 and textual_preferences_retirement_v1 steps in that order. Legacy session project bindings become catalog bindings. Historical Textual-only preferences are omitted instead of being copied into browser preferences. Project repositories, .giga/ directories, provider homes, credentials, prompts, and provider output are not read or changed.

The migration is resumable after every durable boundary and emits a content-free receipt under the active state migrations/ directory. Keep the archive and its adjacent private migration support directory together until the candidate is accepted. Re-running the exact command with the same backup path returns the same verified receipt.

To recover, stop GigaLoom and atomically restore the pre-upgrade archive:

giga state verify ../gigaloom-before-0.7.zip --json
giga state restore ../gigaloom-before-0.7.zip --replace --json

Restore the archive before reinstalling 0.6. Reverse schema migration and merging old and new state trees are not supported.

Roll back an upgrade

Before state migration, stop GigaLoom and reinstall the exact previously used version. After migration has started, keep 0.6 installed long enough to restore the verified backup first:

giga state rollback
uv tool install --force --prerelease allow 'gigaloom==0.5.1a2'

giga state rollback restores the historical root from ~/.gigaloom-migration and preserves ~/.gigaloom for diagnosis. Do not point an older executable at the canonical 0.6 root, merge the two roots manually, or delete either root until the rollback is verified. Project .giga/ state and provider-owned homes are not migrated or rolled back by this command.

Package downgrade is separate from release rollback: published registry versions and their v... tags are immutable and are never overwritten or moved.

Optional gateway preset

The base package does not require gpt2giga. Install the optional extra only for Direct Chat or the legacy local-gateway preset:

uv tool install 'gigaloom[gpt2giga]==0.9.1'

This installs the supported stable gateway range; the committed development and release lock resolves one exact public artifact. It does not require a gateway repository, sibling checkout, editable dependency, or submodule. See Gateway integration.

Consume the Web package without Python

Services that host the verified static Cockpit assets independently can install the matching npm release:

npm install --save-exact @gigaloom/web@0.9.1

Mount the package's dist/ directory at /web/assets/ and serve dist/index.html for operator routes. Preserve hashed filenames and verify the included content manifest; the package is not a React component library and does not include the Python server. The Python wheel embeds the same Web bytes.

Remove

uv tool uninstall gigaloom

Package removal does not delete user state under ~/.gigaloom. Back up or remove that state separately after reading Operations.