# SwarmUI operator guide SwarmUI brings connection setup, Cohesix operations, namespace exploration and verified run stories into one desktop. Spectrum provides controls and accessible focus; PixiJS renders the hive and causal ownership map. All assets are local. ## Connect your hive Open **SwarmUI.app** from the verified macOS desktop package, or **bin/swarmui** from the Linux AArch64 desktop package in a graphical session. Jetson uses the same Linux desktop contract. Keep the package together: its `bin/coh` supplies the matching validated host operations. **Settings → Installed tools** can select another matching installation with the native folder chooser. For a native M28g Mac installation, SwarmUI in `/Applications` looks for `coh` and the gateway under `/Library/Application Support/Cohesix/bin` without a shell `PATH` or bundle-root working directory. The GNOME desktop entry opens `/usr/lib/cohesix/bin/swarmui`; its matching tools are in the same directory. These are candidate install paths until the native installer and launch checks in the M28g record pass. The Mac candidate's Dock icon is a navy tile with the orange Cohesix circuit around a three-node swarm; the package embeds it in `SwarmUI.app` before signing. 1. Select **Connect a hive**. Choose **Hive Gateway** for shared access, or **Queen directly** for a single-owner TCP console. 2. Enter the gateway base URL (`https://gateway.example:8443`) or Queen address (`tcp://192.0.2.10:31337`). A gateway URL has no path, query or embedded password. 3. Enter your request-auth credential for a gateway, or TCP authentication credential for a Queen. `env:NAME` and `file:/absolute/path` references work; placeholder credentials fail before connecting. Select your role and, where required, a separately scoped delegated ticket or secret reference. The gateway transport supports the Queen role with scoped delegation; Worker roles use direct TCP. Gateway connection verifies authenticated status and upstream reachability before displaying LIVE. 4. Select **Connect**. The app reports authentication refusal without becoming live. A successful connection shows **LIVE**, endpoint and role. A named profile saves only the endpoint, transport, role and name. It saves no secrets. A Queen console has one owner. Close another direct client before connecting, or use a Hive Gateway which owns that console and multiplexes clients. Live host operations require a gateway so an invoked tool cannot steal a direct session. Gateway status and pressure appear in the hive; exact refusals remain in the transcript. Disconnect explicitly before switching operators. Changing connection, replay or installed tools invalidates an outstanding action review. Environment-based launch configuration (`SWARMUI_TRANSPORT`, `SWARMUI_9P_HOST`, `SWARMUI_9P_PORT`, `SWARMUI_REST_URL`, and the documented auth references) remains available for existing deployments. The ordinary graphical journey needs none. Raw Secure9P launch mode remains an advanced compatibility transport. ## Find help Hover or focus the **?** beside a screen title for a short next-step hint in plain English; tap it on a touch screen. **Escape** dismisses the hint. Presentation, transcript, Recent activity and snapshot naming have similarly brief tooltips. Important input and authority guidance stays visible in the forms. **Find an action** searches operations, and the optional console provides `help` and `man` usage. ## Run a local Metal model on Mac On the supported Apple Silicon Mac, open **Local MLX**. Select the absolute `bin/python` path of a private environment containing this Cohesix Python package and the pinned `apple-mlx` extra, then select a private JSON profile with absolute model/data paths, their `tree_digest` SHA-256 values, a Metal memory limit, and optional adapter path and digest. The selected source checkout provides the setup command and profile fields in [Host Tools](HOST_TOOLS.md#swarmui). Enter a bounded prompt and choose **Run local inference**, or choose **Measure held-out loss** to evaluate the profile's independent test rows. The panel reports the observed Metal device, artifact hashes, peak memory and response or loss. It labels these as local observations. A missing runtime, changed file or unavailable Metal GPU refuses; no remote or CPU fallback is selected. Python `train_lora` creates the adapter before it is selected here. The adjacent **Governed release** controls use `coh` and need a separately admitted deployment; a model answer or local loss never becomes its signed outcome. Installed vMLX compatibility is optional and does not gate direct local MLX work. For the selected Mac release, use **Follow** on the original successful promotion and the separately admitted failed candidate's rollback. Once both signed graph IDs appear in the desk, select the retained 28c1 vMLX report in **Governed vMLX observation**. SwarmUI shows the accepted generation, fused model hash, frozen response count and observed resource bounds only when both graph IDs match those inspected in this session. This is a projection of selected-host evidence, not a new admission or vMLX tool endpoint. A changed generation or missing rollback report is refused. ## Explore published state Open **Namespaces**, choose a root and select an entry. Directories open as lists; files open as bounded reads. **Read file** and **Recent activity** remain above the listing. A path-kind refusal permits a read-only file probe; authentication and capability refusals stop immediately. The transcript retains both operations, and new selections clear the previous listing so it cannot be mistaken for new state. The preview heading and breadcrumb identify the path of the displayed response, including direct reads, recent activity and refusals. ## Choose an operation **Operations** is generated from the same Rust argument schema as the installed `coh`. Search by purpose or command, select the operation, fill its labelled fields, then **Review action**. Path fields have native file/folder selectors. The review shows the exact argument vector without credentials. Confirming runs that one reviewed request; editing context or replaying a confirmation refuses it. The app checks the installed tool's schema before execution. | Task | Where to go | | --- | --- | | Inspect providers, plan CUDA work, apply/watch/explain/verify/recover a run | Operations | | Plan, apply, inspect or recover a private LoRA release | Operations → Private LoRA release | | GPU discovery, status, leases, model and PEFT registry operations | Operations | | Collect telemetry, attest, build/inspect/export/verify evidence | Operations or Evidence | | Worker lifecycle, budgets, scheduling, leases, bind/mount, policy and approvals | Tickets & policy | | Read target state and control-file status | Namespace | | Read command usage and recovery guidance | Field help or Expert console → `man` | | Replay a verified CUDA or LoRA journey | Run story → reference walkthrough | Controls use existing console records and the selected generated paths. Required identities, numbers, enumerations and hashes are validated before submission. The target still owns role, scope, production-policy and lifecycle admission. A visible control never grants permission. Legacy spawn/kill can be refused by a production profile; use its admitted workflow. An ACK means admission, not Worker readiness, completed execution or independently verified success. Some host operations are deliberately outside a desktop subprocess lifetime: arbitrary shell-backed `coh run`, a persistent FUSE mount and identity-service administration explain their owning service boundary in the catalog. They are not alternate executors. Native preparation and persistent executor/service installation follow [host installation](ADOPTION.md); once enrolled, the accepted CUDA and LoRA controller journeys run through the desktop forms. Only one host operation runs at a time. Output is bounded to 1 MiB per stream; the controller process has a 120-second bound. Timeout is **interrupted/unknown**: terminating a controller does not prove cancellation of remote work. Retain the operation identity and deployment file, then use its **Watch**, **Explain** or **Recover** form. Do not create a new identity merely to retry an ambiguous run. The window refuses to close while the bounded controller is running. ## Explore and inspect **Namespace** offers generated roots, breadcrumbs, list/read/tail actions, copy path and transcript access. Paths are absolute, at most eight components and 96 bytes; relative walks, `.` and `..` are refused. Role/ticket scope is enforced by the owning transport. Canonical Worker telemetry lives at `/shard/