Installation & Launch

Install paths, shells, version pinning, troubleshooting

Cockpit Installation & Launch

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Cockpit is opt-in and separately published as `@aiwg/cockpit`. It is not part of the base `aiwg` npm package (a smoke test guards that boundary), and its version is kept in lockstep with the base AIWG CalVer version.

Recommended path: through the base CLI

Use AIWG to complete this documented outcome: Recommended path: through the base CLI
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

the agent-owned use operation installs the package outside the base package footprint, under `~/.aiwg/cockpit/package` (override the root with `AIWG_COCKPIT_HOME`), pinned to the installed AIWG version. the agent-owned cockpit operation then launches the local Bridge, which serves the web UI through a one-time bootstrap and HttpOnly session.

Useful flags on the launcher:

Flag	Effect
the agent-owned cockpit operation	Report install state and version lockstep
the agent-owned cockpit operation (or the y option / the yes option)	Install/refresh the package, then launch

Direct npm install (package testing)

Use AIWG to complete this documented outcome: Direct npm install (package testing)
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

If a direct global install fails with `EACCES`, apply the npm global-prefix fix from the root AIWG README — or prefer the base-CLI path above, which avoids global-prefix permissions entirely.

What launching does

the agent-owned cockpit operation (or `aiwg-cockpit`) starts the Bridge on `127.0.0.1:8140`:

1. Generates a per-launch bearer token and writes `~/.aiwg/cockpit/runtime/bridge.json` (file mode 600, directory 700), storing the token in the OS keychain when one is available (macOS Keychain, Windows Credential Manager, libsecret; KWallet opt-in). 2. Probes the agentic-sandbox executor at `AIWG_COCKPIT_EXECUTOR_URL` (default `http://127.0.0.1:8122`); if unreachable, best-effort autostarts an installed `agentic-mgmt` binary (disable with `AIWG_COCKPIT_AUTOSTART_EXECUTOR=0`, pin the command with `AIWG_COCKPIT_EXECUTOR_COMMAND`). 3. Prints a 60-second, one-time browser bootstrap URL whose nonce is in the fragment. The reusable bearer never enters the URL.

Open that printed URL rather than the bare `http://127.0.0.1:8140/` address. If the Bridge is already running and the printed URL has expired, mint a fresh one from the same host and user account that launched Cockpit:

node the input-type option=module -e '
  const moduleUrl = `file://${process.env.HOME}/.aiwg/cockpit/package/node_modules/@aiwg/cockpit/shell-core/runtime.mjs`;
  const { connect, webviewUrl } = await import(moduleUrl);
  const runtime = await connect();
  console.log(await webviewUrl(runtime));
'

This command targets the default managed installation. In a source checkout, replace `moduleUrl` with `new URL('./apps/cockpit/shell-core/runtime.mjs', import.meta.url)`. The result is a browser URL containing a one-time, browser-audience bootstrap nonce valid for 60 seconds. It is safe to pass through an SSH local-forward because only the short-lived nonce enters the URL; the reusable Bridge bearer remains in the runtime file or OS keychain on the Cockpit host. With the standard local forward (`localhost:8140` to the Cockpit host's `127.0.0.1:8140`), open the printed URL unchanged on the local machine.

Point at a different executor:

AIWG_COCKPIT_EXECUTOR_URL=http://127.0.0.1:8122 the agent-owned cockpit operation

The full environment-variable reference lives in Bridge API → Environment variables.

Other shells

Every shell resolves the Bridge the same way: read `~/.aiwg/cockpit/runtime/bridge.json` → `{token | token_ref, port}` → resolve the token (keychain ref preferred) → poll `/healthz` and the authed `/api/health` → request an audience-bound nonce → load `http://127.0.0.1:<port>/#bootstrap=<one-time-nonce>`.

Desktop (Tauri) — a native window hosting the same Bridge UI. Build/run

from `apps/cockpit/desktop` with `cargo tauri dev` / `cargo tauri build` (Linux needs webkit2gtk-4.1, libsoup-3.0, libappindicator; artifacts are .deb/.rpm/.AppImage). The window waits for `bridge.json`, then opens the one-time bootstrap URL.

VS Code — the `aiwg-cockpit` extension (`apps/cockpit/vscode`) opens the

UI in a webview via the AIWG Cockpit: Open command. Launch the Bridge first. The `aiwg-cockpit.bridgeRuntimeFile` setting overrides the runtime file location. Note: on Windows the extension cannot yet resolve keychain-backed tokens (Credential Manager backend not implemented in the extension); use a platform where the runtime file carries the token or track the fix in the issue tracker.

Dev workspace — see Development for

`npm run cockpit:up` and the Cockpit-only `npm the prefix option apps/cockpit run dev`.

Troubleshooting

Symptom	Fix
the agent-owned cockpit operation reports Cockpit is not installed	the agent-owned use operation
Installed version doesn't match base AIWG	the agent-owned use operation (reinstalls in lockstep)
Bridge refuses to start on port 8120/8121/8122	Intentional — those are the executor's canonical ports. Use the default `8140` or set `PORT`/`AIWG_COCKPIT_BRIDGE_PORT` to another free port. See Development → Ports
UI shows "No stack connected"	The executor isn't reachable at `AIWG_COCKPIT_EXECUTOR_URL`. Start one (see Development) or fix the URL. If you pointed at the bundled mock: the Bridge refuses mock executors for human launches by design
Shell can't authenticate	Delete `~/.aiwg/cockpit/runtime/bridge.json` and relaunch to mint a fresh token; check keychain availability, or see `AIWG_COCKPIT_KEYCHAIN_*` in Trust & Security