Installation & Launch

Install paths, shells, version pinning, troubleshooting

Cockpit Installation & Launch

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.

npm i -g aiwg
aiwg use cockpit     # installs @aiwg/cockpit under ~/.aiwg/cockpit/package
aiwg cockpit --status
aiwg cockpit

`aiwg use cockpit` 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. `aiwg cockpit` then launches the local Bridge, which serves the web UI token-injected.

Useful flags on the launcher:

FlagEffect
`aiwg cockpit --status`Report install state and version lockstep
`aiwg cockpit --install` (or `-y` / `--yes`)Install/refresh the package, then launch

Direct npm install (package testing)

npm i -g @aiwg/cockpit
aiwg-cockpit          # bin → bridge/src/server.mjs

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

`aiwg cockpit` (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. Serves the built React UI at `http://127.0.0.1:8140/?token=…`.

Point at a different executor:

AIWG_COCKPIT_EXECUTOR_URL=http://127.0.0.1:8122 aiwg cockpit

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` → load `http://127.0.0.1:<port>/?token=<token>`.

  • 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 token 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.

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

Troubleshooting

SymptomFix
`aiwg cockpit` reports Cockpit is not installed`aiwg use cockpit`
Installed version doesn't match base AIWG`aiwg use cockpit` (reinstalls in lockstep)
Bridge refuses to start on port 8120/8121/8122Intentional — 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 authenticateDelete `~/.aiwg/cockpit/runtime/bridge.json` and relaunch to mint a fresh token; check keychain availability, or see `AIWG_COCKPIT_KEYCHAIN_*` in Trust & Security

See also