Reference

States and Security

State determines what can be done now. Security boundaries determine what must not be leaked or bypassed even when an action is technically possible. Development must satisfy both kinds of constraint.

Workspace state decisions

State	Can SSH/SCP/WebChat be used?	Action
Non-terminal creation state	No	Let the CLI keep polling. After a timeout, query the same Workspace ID
`active`	WebChat only while `connection_status=ready`; SSH/SCP only after `workspace connect` returns `bound + ssh_verified=true`	Use only the exact commands and URLs from the current result and observe `expires_at`. With authorization, use `workspace resume` for an expired connection
`failed`	No	Record `failure_code` and stop connection attempts
`closed`	No	Terminal state; `workspace resume` cannot reopen it
`published`	No	Terminal state; view the published version on the website
`cleanup_pending`	No	The platform is cleaning up; do not keep writing
`close_pending`	No	The platform is closing the Workspace; do not keep writing

A timeout is not a terminal state

WORKSPACE_TIMEOUT means only that this bounded wait expired. Preserve the workspace_id and last_status in the error, then run workspace status. Do not create another Workspace.

Publish, version, and Agent supply states

A Publish Job and publication visibility are related but separate state axes. The version's online/offline state displayed on the page and the Agent-level supply_status are two more distinct fields. For routine developer actions, use the page's Online/Offline state. When diagnosing APIs, do not mix the terms.

Layer	Key states	Completion gate
Publish Job	`queued` → `running` → `succeeded`; or `failed`/`canceled`	`succeeded`
Publication	`pending` → `syncing` → `visible`; or `failed`	`visible`
Version / UI	`offline` / `online`	The page must show Online before the version accepts formal invocations
Agent supply	`suspended` / `listed`	When online, it should also be `listed`. Do not call this layer Online/Offline

A recommended completion condition is:

publish_job == "succeeded"
and publication == "visible"
and version_status == "online"
and supply_status == "listed"
and real_invocation_verified == true

When authentication is required, the CLI opens a browser and applies four key protections:

Loopback callback: the callback binds only to the local loopback address; the developer does not copy an access token.
state: binds the authorization response to this request and rejects a mismatched callback.
PKCE: uses challenge/verifier material between the authorization request and session exchange.
one-time code: the browser returns a single-use code instead of placing a long-lived token in the URL.

Credentials go only into secure system storage

Platform	Storage used by the CLI
Windows	Windows Credential Manager
macOS	Keychain
Linux	Secret Service (`secret-tool`)

If secure storage is unavailable, the CLI returns credential_store=unavailable and does not fall back to writing the session in plaintext to an ordinary configuration file. Never use a custom script to store a Token in the project directory, shell history, or an environment snapshot.

SSH key boundaries

Do

First run the non-mutating ssh-key ensure to locate an existing key.
Add --create only after the user explicitly approves key creation.
Keep the private key on the local machine; the platform receives only one OpenSSH public-key line.
Run workspace connect and use the exact SSH/SCP commands it returns only after ssh_binding_status=bound and ssh_verified=true.

Never

Overwrite an existing key file.
Upload a private key or paste it into a webpage or chat.
Guess connection parameters when the Workspace ID, Version ID, or host information is uncertain.
Write credentials under /oasn or commit them to version control.

Redaction in logs, screenshots, and collaboration

Remove Tokens, Cookies, Authorization headers, and all private keys.
If an SSH/SCP command contains a temporary host, username, or connection material, retain only the part required for diagnosis.
Crop account email addresses, balances, browser password prompts, and personal names in system paths from screenshots.
An error code, state, Workspace ID, and Version ID may be recorded; apply your team's ID-handling policy before sending them externally.
Do not copy CLI secure-store contents or browser callback URLs into a ticket.

Control-plane boundaries

The website and CLI are the public developer control planes. CLI 0.7.3 provides workspace sources, workspace resume, version webui-ports get/set/refresh, and an allow-listed portal surface that includes publishing and supply-state operations. Portal writes require explicit authorization, --confirm, and any idempotency/ETag inputs required by that command. The website form still has no WebUI-port field, and there is still no public Workspace close command or generic file sync command. These boundaries must not be bypassed by guessing internal URLs, reusing service credentials, or writing custom database/API requests.