Documentation

Secure input

Generated reference for Secure input, including its syntax, options, results, and constraints from the canonical cockpit CLI source.

Applies to
CLI
WindowsmacOSLinux

Verified 2026-08-27 · v4.61.0

Markdown

Some screens and steps may differ in the latest version.

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

cockpit secret requests a single use of a secret in a fixed browser password field, a specific Cockpit-managed task terminal, or a Crew's chat connection. It is separate from Ask: the value never becomes an Ask answer, chat message, queued message, CLI result, diagnostic event, or persisted task state.

cockpit secret request --label "Cloudflare password" --summary "Fill the password field on this login page" --to browser --tab <tabId> --selector 'input[type="password"]' --expires-in 10m
cockpit secret request --label "NAS password" --summary "Enter the password at the checked NAS prompt" --to terminal --terminal <terminalId> --expires-in 5m
cockpit secret request --to crew --crew <crew> --platform discord --expires-in 10m   # Same as cockpit crew connect <crew> --platform discord --secure-input
cockpit secret status <requestId>
cockpit secret cancel <requestId>

All three commands require the authenticated requesting task's local CLI context. The task's secret capability is checked independently of the general CLI token; knowing a request ID or choosing another task ID grants no access. The CLI can use the local file IPC bridge for metadata if loopback is blocked before connection; the input value never uses that bridge. A request is never retried after a connection was established. Remote-target CLI calls are unsupported; use the PWA on the requesting PC's HTTPS connection to enter the value. There is no secret value argument, stdin value, get, reveal, external Terminal.app access, or Vault.

request returns immediately with id, status, and expiresAt. status and cancel return the same metadata and a value-free result when available. Every response carries instance (production, dev, or dev-task-<hash>) like other commands, so a request sent to the wrong Cockpit instance is visible. The default expiry is ten minutes from creation. --expires-in accepts whole seconds (30s) or minutes (5m), up to ten minutes. Single use is always enforced; --once is unnecessary. Labels and summaries describe the purpose, and must not contain credentials.

A request appears where Asks do: on the desktop in its own small window (like an Ask window, controlled by notifications.askWindow) and in the side panel Ask tab (cockpit side-panel ask), and in the PWA Inbox next to Asks and displays. It plays the Ask chime (notifications.askSound), shows the default medium priority badge, and is ordered with Asks. Because the window is separate from the main window, the in-app browser never covers it; hiding the window keeps the request in the Ask tab. Only the presentation is shared: a secure input request is not an Ask. It never appears in cockpit ask list, cannot be answered with cockpit ask answer, is never sent to Discord or Slack (a Crew's owners get only a DM that one waits, below), never fires ask.* Hooks, never produces cockpit.ask.resolved, and accepts no attachments.

When a Crew or one of its child tasks makes a request and Remote Access runs over HTTPS, Cockpit also tells each owner of the Crew's chat connection by DM, from the Crew's own bot, that a secret is waiting, with the PWA address (https://<domain>:<port>/, without a token or the request ID), and updates that DM once the request ends. The DM never carries the label, summary, destination, or value. It follows the Crew's --ask-dm and --ask-dm-to settings (cockpit help crew); without HTTPS Remote Access Cockpit sends no DM, since the PWA takes a secret only over HTTPS.

A browser request shows the requesting PC, task, purpose, Browser Identity, actual page URL/origin, main frame, selector, and deadline before accepting a masked input. Submit with Fill this field once (日本語: この入力欄に一度だけ入力). Only a unique, visible, enabled password input in the main frame can be used, on HTTPS or loopback HTTP. The original document and element are bound at creation; navigation, replacement, permissions changes, or an ambiguous selector fail closed. No alternative field is chosen. Form submission and login-button clicks are never automatic.

Managed terminal input

Use --to terminal --terminal <terminalId> for a terminal session belonging to the requesting task. Obtain the exact session ID from cockpit side-panel terminal status --json; --terminal task explicitly selects the requesting task’s primary PTY instead. No terminal is created or selected implicitly, and another task’s terminal cannot be targeted. Browser-only --tab / --selector options cannot be mixed with this target. External Terminal.app and terminals created by other tools are unsupported.

Before creating a request, Cockpit inspects the managed Unix PTY’s echo and canonical line-input flags and foreground process group. It requires echo off, line input enabled, and an identifiable foreground process. Echo-on shells, raw-mode terminals, Windows ConPTY, and unavailable mode inspection fail with terminal_input_unverified; nothing is sent. These checks do not prove that a password read is waiting and do not authenticate an SSH host or other remote destination. Check the actual prompt and destination yourself. No prompt-text heuristic is used. Do not use this for an untrusted receiving program.

The secure input screen shows the PC, task, terminal name and ID, unique PTY session, foreground process group, detected mode, and deadline. The user must confirm that the terminal is waiting for a password and that its destination is correct. Send once and press Enter (日本語: 一度だけ送信してEnterを押す) writes the value followed by one Enter to that PTY. completed means the PTY write was accepted; it does not mean SSH authentication succeeded. Only one line with no control characters, up to 512 UTF-8 bytes, is accepted.

The original PTY instance, foreground process group and start time, input/output revisions, mode, and deadline are checked again immediately before writing. Any intervening input/output, process change, terminal exit, replacement, or task end invalidates the pending request; there is no fallback or queued retry. Pending terminal requests are also checked every second using asynchronous OS inspection, with at most four inspections active across requests. Status/list reads perform only in-memory lifecycle and revision checks; they do not spawn inspection commands. Delivery always performs a fresh OS inspection and checks the deadline again after it and immediately before writing. OS inspection is a point-in-time observation, not an atomic guarantee about the receiving program’s next read. Cancel or expiry before delivery prevents writing; once writing starts, cancellation cannot undo it.

Before writing, Cockpit installs an output filter upstream of live terminal clients, output-reading tools, headless scrollback, and snapshot persistence. It redacts the exact supplied value even when split across PTY chunks or reprinted later. Only comparison hashes and matching state are retained for that PTY’s lifetime. Overlapping values are all protected, including a corrected password that extends an earlier one. A possible matching output prefix is held for up to 100 ms of idle time, then emitted as separate mask characters while retaining comparison state so a delayed continuation cannot expose the value. Adjacent masks are never merged, including across chunks or pauses. This can mask unrelated text that happens to match a protected prefix. CSI terminal control sequences are preserved whole as protocol, including color resets and cursor-position queries split across idle periods; the filter protects text, not encoded or transformed representations. Pending output and matching state are discarded at session end. Up to 100 secure deliveries per PTY are supported. Protected PTY errors use fixed descriptions without native error contents. The receiving program can retain or transform the value; transformed/encoded output and compromised destinations are outside this protection. Cockpit cannot verify the password or the remote server.

Crew connection token

Use --to crew --crew <crew> --platform discord (or cockpit crew connect <crew> --platform discord --secure-input) to have the owner paste a Crew's Discord bot token, which Cockpit then uses to connect that Crew exactly as cockpit crew connect --token-stdin and Settings do. The token never passes through the requesting task's shell or context. --label and --summary are optional here; Cockpit fills them in. The owner's own tasks and the master may ask for any Crew. A Crew's own session may ask only for itself and only in a turn the owner started (owner_request_required in another turn, not_allowed_for_crew for another Crew), and a Crew's child task gets forbidden_from_crew. An unknown Crew gets crew_not_found, another platform platform_invalid.

The secure input screen shows the PC, task, Crew name and id, the platform, and the account it is connected as now, which the token replaces. Connect with this token (日本語: このトークンで接続) checks the token with Discord, where Cockpit also turns on the Message Content Intent when it can, and on success keeps it as the Crew's credentials in this computer's secure storage, as Settings does; this kind of request stores the value on purpose, unlike the others. The value must be a single line of up to 512 bytes. If the Crew is removed, or its connection changes to another account, before the owner submits, the request fails with destination_unavailable and stores nothing. The check can take longer than other deliveries; Cockpit waits up to 90 seconds before reporting unconfirmed.

The result tells the task what happened without the token: input_completed when the Crew is connected, and for failed one of token_invalid (Discord rejected it; ask for a token copied again with Reset Token), intent_disabled (the intent is off and Cockpit could not turn it on), app_in_use (the application is used by Ask notifications or another Crew), setup_changed (the connection changed meanwhile), or connect_failed. A request closes when it settles, so to try again, ask again. After input_completed, continue with cockpit crew invite-url <crew>.

Shared delivery lifecycle

PWA input requires authenticated WSS over HTTPS. An unencrypted connection cannot submit or cancel, and never falls back automatically. Desktop input uses trusted IPC from the main window or the request's own window. Both use the same server-side single-use state machine. Simultaneous submissions consume the permission only once and synchronize the authoritative state to all clients; draft values are cleared when a request leaves the waiting state or the client disconnects, closes, or hides the input.

States: pending (waiting), delivering (sending once), completed (input completed), expired, canceled, failed (destination unavailable), and unconfirmed (delivery result unknown). A lost acknowledgement never causes automatic retry. Reconnect to check status; do not resend an unconfirmed delivery. Cancel affects only a pending request, and cannot undo input that has started. For terminal targets, results are read with secret status when the target is the primary task PTY or the requesting task is a plain terminal task; no notification text is written into these shells or password prompts. Other result notifications sent to the requesting task contain only the request ID, status, and result, including when that task is busy. Notifications preserve the task’s model, effort, and approval mode. Settled request metadata is available to status for one minute, with at most 100 settled requests retained in memory. After removal, status returns secret_request_unavailable; removal never permits another delivery. A request leaves every desktop and PWA surface as soon as it is no longer pending or delivering; nothing stays on screen to show the result or an empty count. Read the result with cockpit secret status or the cockpit.secret.result notification.

Errors

A failure prints {"ok":false,"code":"...","error":"...","instance":"..."} and exits with status 1. Branch on code; error is a fixed description. No error contains an input value or page content. A failed request creates no request, except secret_outcome_unknown, whose outcome is unknown. A restored tab that is not loaded yet is loaded first, as with other browser commands.

code Meaning and recovery
invalid_secret_command Use request, status, or cancel.
invalid_secret_options A missing, repeated, unknown, or out-of-range option (for example --expires-in above 10m, a label over 200 characters, or a summary over 2000).
invalid_request_id The argument is not a request ID.
authenticated_task_required Run the command from the requesting task launched by AGI Cockpit while it is still running; the CLI sends the task's secret only to the Cockpit that launched it.
secret_request_unavailable The request ID does not exist, belongs to another task, or passed its one-minute retention.
secret_request_limit 100 requests are already waiting; settle or cancel some first.
secret_request_expired The deadline passed while the destination was being prepared; request again with a longer --expires-in.
terminal_not_found The specified managed PTY is absent, closed, or not started; check the session ID.
terminal_not_owned The terminal belongs to another task.
terminal_input_unverified Echo-off canonical line input or the foreground process cannot be verified; no delivery. Inspect the prompt and request again only when it is ready.
tab_not_found The tab does not exist or was closed; open the page again.
tab_not_owned The tab belongs to another task; open the page in a tab of this task.
browser_access_denied The tab's Browser Identity is no longer assigned to this task.
insecure_origin The page is neither HTTPS nor loopback HTTP (localhost, 127.0.0.1, [::1]).
invalid_selector --selector is not a valid CSS selector.
element_not_found The selector matches nothing in the main frame.
ambiguous_selector The selector matches more than one element; make it unique.
not_main_frame The selector matches only inside an iframe; only the main frame can be used.
invalid_target_field The element is not a password input, or is hidden, disabled, or read-only.
destination_changed The page navigated or the tab was replaced while the request was being prepared; check the page and request again.
destination_unavailable The tab did not finish loading, its renderer crashed or stopped responding, or preparation failed for another reason. Check the tab (cockpit browser tabs health, tab recreate) and request again.
crew_not_found No Crew has that id or name.
platform_invalid The Crew cannot connect to that platform; use discord.
not_allowed_for_crew A Crew's own session asked for another Crew's connection token; the owner's task or the master can.
owner_request_required A Crew's own session asked for its own connection token in a turn the owner did not start.
forbidden_from_crew A Crew's child task asked for a Crew's connection token.
cockpit_unreachable AGI Cockpit could not be reached and nothing was sent.
secret_outcome_unknown The connection was lost after the command was sent. A request may have been created and is shown to the user; do not resend automatically.

host_not_supported (with --host) and, on Windows, node_runtime_unavailable / node_runtime_failed are reported by the launcher before the command runs.

Delivery values stay in transient memory, never on disk, in PWA storage/cache, or in Ask forwarding, except that a Crew connection token is saved as that Crew's credentials once Discord accepts it. Requests are not restored after restart, and values are never restored or resent. Task completion, deletion, expiry, cancellation, and delivery completion/failure release delivery copies. This consumes Cockpit's permission to deliver once; it does not guarantee external exactly-once execution or complete erasure of all memory.

The destination site can retain the field value and tools that read its DOM or evaluate scripts may read it after input. The feature does not promise that AI cannot read destination data. It assumes trusted PC/PWA/destination devices; it is not isolation from a compromised device. Discarding Cockpit's delivery copy does not clear the destination field.