Transport & Sandbox

This reference is generated from the same canonical source distributed as cockpit CLI help. See Cockpit CLI for concepts and safe operating guidance.

The cockpit CLI talks to the AGI Cockpit app over loopback HTTP (127.0.0.1), with an automatic file-based IPC fallback (AGI_COCKPIT_IPC_DIR) when a sandbox blocks network access. The fallback is limited to the Cockpit instance that supplied that IPC directory; an explicit connection is never redirected through another instance's runtime file. Commands therefore work identically in restricted sandboxes — never request escalated, full-access, or network permissions to run cockpit commands; doing so only pops a needless approval prompt.

Before task, talk, HTML, or side-panel commands run, the CLI authenticates the task API through loopback and then file IPC if needed. The complete preflight has one two-second wall-clock budget, including process startup. Loopback receives at most 500 ms, leaving at least 1.5 seconds for file IPC. A transport timeout is not authentication success and never prevents the next transport from being tried. Internal recovery paths may accept a final timeout only after all available transports have been attempted; cockpit doctor still reports such a result as unauthenticated.

Each file IPC request is written once, under a fresh request id, and the CLI then only waits for the matching response file — it never re-submits a request that is still in flight, so a task create or task send is not at risk of running twice. Loopback exit 7 means no connection was established, so the file IPC fallback that follows it delivers the request for the first time rather than repeating it. Timed-out request files are removed immediately; a late response remains covered by the bridge's existing orphan-file garbage collection.

If a command fails with exit code 7 or {"ok":false,"error":"Cannot reach AGI Cockpit ..."}, that is a transport availability issue: AGI Cockpit is not running, or an old CLI lacks the file bridge. It is NOT a permissions or argument problem — do not retry with elevated network permissions or different arguments. Make sure AGI Cockpit is running, then re-run the exact command.

cockpit doctor compares cli-runtime.json with AGI_COCKPIT_*_PORT overrides. It distinguishes PID visibility, direct loopback reachability, file IPC reachability, and the authenticated effective transport. It also reports the resolved local instance — the Cockpit the CLI will actually send to, not merely the profile that shipped the binary. Use it when task or talk commands fail with exit 7; the per-transport result identifies which path was attempted and why it failed. A CLI pinned to one local instance does not follow inherited AGI_COCKPIT_* connection settings that point at another; it fails with instance_mismatch instead of sending. --host commands omit instance because they are not talking to that local target.