Guaca v0.2.0

Guaca is a macOS desktop app for groups of AI agents that communicate, delegate work, and work across repositories.

This release is a universal macOS build from commit c15bd9a58d5e4406c92f4ad65ca263a35d68a492 on main, tagged v0.2.0.

Changes since v0.1.0

• Group secrets. A group has a Secrets tab where the operator saves a service label, an environment variable, a value, and the agents allowed to use it. A granted secret reaches coding jobs, repository shells, and computer commands as an environment variable, is never rendered into a prompt or the webview, and is scrubbed from Guaca output. See docs/SECRETS.md.
• Reasoning effort on ChatGPT. The app, a group, and an agent each carry a reasoning-effort setting that inherits independently of the model. The selector follows the effective model and its supported efforts from the account's catalog.
• The ChatGPT model selector reads the signed-in account's live catalog instead of a list compiled into the app. Retired saved models stay selectable and are marked unlisted.
• Agent model selection is explicit about inheritance. A blank model means the group default, the profile names the inherited provider and model, and Claude-paid agents explain that Claude controls the model.
• Host update checks. Settings > Workspace reports the installed release, API compatibility, and the latest published stable release, read from this repository's release feed at most once per six hours. The desktop's local host manager offers Back up and update host when its embedded image differs from the running container's, and backs up the volume before replacing it. See docs/UPDATES.md and docs/HOSTING.md.
• File handling fixes. An agent can reopen a saved attachment by name through read_file in chunks, forwarding needs no machine, an explicit path reads current bytes, and a send with a missing attachment delivers nothing rather than text without its file. Native downloads verify the content digest and write to Downloads without navigating the webview; browser downloads use attachment disposition.
• Granted plugin tools are offered before the general workspace tools, which restored Gmail sends that a ChatGPT-paid turn was describing as unavailable. The prompt lists each granted tool by name and an escalation about missing access is reported as historical.
• A coding job's result names the harness that actually ran, so a Claude login failure is no longer reported as a Codex one, and the harness selector keeps showing the saved repository row while a write is pending.
• The signed macOS release procedure is documented in docs/RELEASING.md.

Installation

Download Guaca_0.2.0_universal.dmg, open it, and drag Guaca into Applications. The download supports Apple Silicon and Intel Macs. Node.js, Rust, and a source checkout are not needed.

Choose On this Mac for a Docker workspace, or Remote host for an existing compatible backend. Docker is required on the Mac for local workspaces. Configure model providers, plugins, coding-harness sign-ins, and secrets on the backend.

Backend image

This desktop is pinned to ghcr.io/madebywelch/guaca/guacad@sha256:a3208035a5978924e874b4dcb4fb8f3bdcc1eb2dd715e0ee4f2acfa7bd73bc1b, a multi-platform image (linux/arm64, linux/amd64) built from the same commit with GUACA_RELEASE=1.

The image is not yet on GHCR. Pushing it needs a GitHub token with the write:packages scope, which the release machine's gh sign-in does not carry, so the push was refused with permission_denied: The token provided does not match expected scopes. The image was built to an OCI layout kept beside the artifacts, and its index digest is what the desktop pins; copying that layout to the registry preserves the digest byte for byte. Until the copy is made and the package is set to public, On this Mac cannot pull the backend on a fresh install, and the update feed must not be published. Steps, from the release machine:

gh auth refresh -h github.com -s read:packages,write:packages
gh auth token | docker login ghcr.io -u madebywelch --password-stdin
regctl image copy ocidir:///Users/robert/Development/guaca/src-tauri/target/releases/c15bd9a58d5e4406c92f4ad65ca263a35d68a492/guacad-oci:0.2.0 ghcr.io/madebywelch/guaca/guacad:0.2.0
regctl image digest ghcr.io/madebywelch/guaca/guacad:0.2.0   # must print the digest above

Then make the guaca/guacad package public in GitHub package settings and confirm an anonymous pull on both architectures before publishing this release.

Upgrading from v0.1.0

• Databases move forward through migrations 52 and 53 (secrets and reasoning effort) on first start of the new backend. Migrations are forward-only; do not run a v0.1.0 backend against an upgraded volume.
• On a Mac with a v0.1.0 local workspace, open Settings > Workspace after installing and choose Back up and update host. The manager pulls the pinned image, stops the container, copies the volume to a backup volume, and only then replaces the container. The port and access key are preserved.
• For a self-hosted backend, stop the service, back up the data volume, set the digest above in the deployment, pull it, and recreate the service. docs/HOSTING.md has the Compose and systemd steps.
• Sign-ins, repositories, and routines carry over on the same volume.

Validation

• Built from a clean detached checkout of c15bd9a58d5e4406c92f4ad65ca263a35d68a492 with locked dependencies (pnpm install --frozen-lockfile, cargo --locked), GUACA_RELEASE=1, GUACA_COMMIT set to that commit, and GUACA_BACKEND_IMAGE pinned to the digest above. The bundle carries both.
• ./scripts/ci.sh passed in full on the final run: lint, typecheck, build, the release metadata contract, 1,641 frontend tests, 17 GitHub credential service tests, rustfmt, Clippy in both configurations, and 3,277 Rust test executions (0 failed, 68 ignored) across the desktop and daemon configurations. Two earlier runs of the same gate on the same commit each failed one different concurrency-sensitive test while the emulated Docker build was competing for the machine (a_fan_out_has_every_peer_working_at_the_same_moment, then host::tests::replacement_is_verified_and_bound_to_the_selected_host); each passed on every isolated rerun and both passed on the quiet full run. Both are timing flakes under load, not regressions.
• ./scripts/image.sh passed: health, token gate, served page, bundled tools, and restart persistence.
• The multi-platform release image was built with the same commit and version; each platform was started from the loaded image and its /health reported the full commit, release: true, and version 0.2.0. The live Docker host test (docker_host_survives_client_and_container_restarts) passed against it.
• Signed with Developer ID Application: Robert Welch (LN79XLHFLT), hardened runtime, secure timestamp. Universal binary: x86_64, arm64.
• Apple notarization accepted with no issues; submission 824d1902-e5dc-4838-9501-cbc22e9c72f4.
• Notarization tickets stapled and validated on the DMG and the app. Gatekeeper accepted both as Notarized Developer ID, and the app passed syspolicy_check distribution.
• Mounted the final stapled DMG read-only and verified the packaged app's signature, Gatekeeper acceptance, and both architectures.
• The SHA-256 checksum describes the final stapled DMG. guaca-release.json was generated from the same checkout after the digest was recorded.
• Not done: a clean-Mac install on Apple Silicon and Intel, and the On this Mac and Remote host first-run flows, which cannot succeed until the backend image is on GHCR and public.

Guaca v0.1.0

Guaca is a macOS desktop app for groups of AI agents that communicate, delegate work, and work across repositories.

This draft contains a universal macOS build from commit 51a502ae81e9fa0fc15e863cada0de2e5c525f16 on main.

Changes

• Show saved repository access and commit identity without repeatedly asking for credentials; change credentials explicitly in Edit.
• Refresh coding-harness sign-in status from the repository panel and report missing Codex authentication before starting model work.
• Connect the desktop to a Docker workspace on your Mac or an always-on remote host.
• Export and import groups, including their conversations, attachments, memory, and working notes.
• Use Claude Code, Codex, or pi for repository work, with updated Git credential handling and caching.
• Use the hosted workspace on phones with improved navigation and a dedicated view for decisions that need your attention.
• Preserve the scope of operator authorizations for email actions.

Installation

Download Guaca_0.1.0_universal.dmg, open it, and drag Guaca into Applications. The download supports Apple Silicon and Intel Macs. Node.js, Rust, and a source checkout are not needed.

Choose On this Mac for a Docker workspace, or Remote host for an existing compatible backend. Docker is required on the Mac for local workspaces. Configure model providers, plugins, and coding-harness sign-ins on the backend.

When migrating from the earlier native-runtime app, use the group import/export flow. Sign-in credentials and repository directories do not transfer; reconnect them before resuming routines.

Before publication

This release remains a draft pending approval and end-to-end installation checks.

The desktop currently references ghcr.io/madebywelch/guaca/guacad:0.1.0, the default in this source revision. Anonymous access to that image was denied during preparation. Local setup on a fresh Mac therefore requires the matching backend image to be published and made publicly pullable. Before public distribution, pin a verified multi-platform backend image by digest and rebuild the desktop against it.

Clean-install checks on Apple Silicon and Intel, plus the local Docker and remote-host flows, remain required before publication. Signing and notarization validate the macOS artifact; they do not validate backend availability.

Validation

• Built from a clean checkout of 51a502ae81e9fa0fc15e863cada0de2e5c525f16 with locked dependencies.
• Frontend checks passed: 1,598 tests. Rust CI checks passed, including formatting, Clippy, Python service tests, and desktop/server test suites. Across Rust configurations and the live Codex authentication check: 3,165 test executions passed, 58 ignored.
• The live Codex authentication check passed without credentials or model usage.
• Signed with Developer ID Application: Robert Welch (LN79XLHFLT).
• Apple notarization accepted with no issues; submission c501cc69-7fb8-4ce3-85a1-0c2d46a78b83.
• Notarization tickets stapled and validated on the app and DMG. Gatekeeper accepted both, and the app passed the distribution policy check.
• Mounted the final DMG and verified the packaged app's signature, Gatekeeper acceptance, and both architectures (x86_64, arm64).
• The SHA-256 checksum describes the final stapled DMG.