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.

Remote control is available for task, autorun, accounts, fleet, hooks, and ask list/answer/close through --host <host|alias>, --port, and --https; other families return host_not_supported for an explicit --host.

The CLI resolves aliases through the local device registry, then connects directly to the target SyncServer. Task, Fleet, Hooks, and Ask control authenticate the same way: a verified Tailscale peer on the same tailnet with the same owner, or a loopback connection, needs no token; any other connection needs a paired bearer token (AGI_COCKPIT_TASK_REMOTE_TOKEN, falling back to AGI_COCKPIT_SYNC_TOKEN). A peer with a different owner and no valid token gets authentication_failed. When the target allows Tailscale only, connections that are neither a Tailscale peer nor loopback are refused even with a token. These responses include device: { host, ip, name }, including server errors, and omit the local instance. Remote connection failures report host_unreachable and never fall back to local file IPC, including when --host is 127.0.0.1. Accounts keeps its existing task transport and supports remote login.

Remote commands never start or wait for the local app. Alias lookup uses local connection data already available from the environment or runtime file; if the registry is unavailable or has no matching alias, the CLI connects to the supplied hostname or address directly. Each local lookup has a two-second timeout. Bash retains its local file IPC fallback for that lookup, including with AGI_COCKPIT_TRANSPORT=file; only requests to the resolved remote API bypass it. Both launchers require the deployed cli-families.tsv capability table and return a JSON file error naming it if it is missing or unreadable.

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. Authentication checks share a 20-second deadline across connection candidates. Loopback receives at most 200 ms before switching to file IPC. The first file response can use the remaining time minus up to 1.5 seconds reserved for checking rejection of an invalid token. File IPC can wait up to 20 seconds for a queued request to be consumed, bounded by the command's own timeout. 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.

While the task listener is recovering, authentication GET requests may be retried within the shared deadline. A changed port is followed only when the runtime still has the same PID, token, and IPC directory; a 401/403 response with the advertised token stops recovery. Bind failures and unexpected listener stops are recorded, retried with increasing delays from 1.5 seconds up to 60 seconds, and use a free port if the previous one is occupied or denied. The runtime advertises the actual port atomically only while its listener is bound. During recovery it leaves the port unadvertised, and the CLI waits within the authentication deadline for the same instance to publish a listening port. Slow HTTP responses alone do not restart a listener. Deliberate shutdown drains active responses for up to one second and closes idle connections; a subsequent start chooses a fresh port.

After recovery completes, commands from existing tasks use the same instance's current advertised port without probing their inherited previous port. A changed or temporarily missing task port alone does not change the instance identity when the task token and IPC directory still match; the caller's task context is retained. Other conflicting connection settings still identify a foreign instance.

The PowerShell launcher does not need Node.js on PATH. File IPC, task authentication through file IPC, cockpit doctor, cockpit secret, and gen-video run on the first available runtime: AGI_COCKPIT_NODE_PATH; the AGI Cockpit executable, started as Node — the running app named by the runtime file, the executable path the runtime file records, or the installed Microsoft Store package, so it works while the app is closed; then node on PATH. With none of them, task commands keep native loopback authentication with a two-second request timeout, and commands that need a runtime return node_runtime_unavailable. A runtime that exits without printing JSON returns node_runtime_failed with its first error line. Both exit 7 on the file IPC transport and 1 otherwise. File transport preserves HTTP status, error body, and timeout information for command error handling and task creation reconciliation; directory-context lookups use the selected transport.

The PowerShell launcher decodes every response as UTF-8 and prints exactly one line of JSON. An HTTP error returns the server's JSON body with its code (a non-JSON body becomes code: "http_error" with status), and an unexpected failure returns code: "unexpected_error" instead of a PowerShell error record. In PowerShell, --stdin also reads pipeline input, such as Get-Content report.html -Raw -Encoding UTF8 | cockpit html show --stdin. PowerShell decodes the file before the CLI sees it, so name the file's encoding, and several piped strings are joined with line feeds; use a --*-file option to send a file's text exactly. An empty pipeline fails with code: "stdin_no_input" instead of a missing-option error and never falls back to the process's own standard input.

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 local 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.