Install CLI and Create a Workspace

oasn-sa-dev 0.7.3 is the controlled local entry point for Developer Workspace operations and an allow-listed adapter for developer features on the OpenAgent website. It handles verified installation, diagnostics, OAuth, source selection, Workspace creation and connection, WebUI-port declarations, and explicitly authorized portal operations. The presence of a command never grants permission to run a write operation.

Secure installation from the trusted prompt

1. Read the platform Skill first

   Give the local AI the complete Build With Local Agent prompt copied from the website. The static Skill supplies the fixed HTTPS URL, file size, and SHA-256 of the CLI deployed for the current environment. Never replace those values with a URL from a chat, an old document, or a third party.

2. Run the bounded bootstrap from the Skill

   The bootstrap verifies HTTPS, the size limit, the response-header digest, and the body digest before it invokes the downloaded file's installer:

   # Windows (Python Launcher)
   py <verified-oasn-sa-dev.py> install --expected-sha256 <Skill-bound-64-character-SHA-256>
   
   # macOS / Linux
   python3 <verified-oasn-sa-dev.py> install --expected-sha256 <Skill-bound-64-character-SHA-256>
   

   
   The placeholders explain the parameters; they are not executable download values. The real bootstrap must use the URL, digest, and Python executable selected by the current Skill. Do not mix the Windows py command with the macOS/Linux python3 command.

3. Record and verify the installation result

   Successful JSON includes version, sha256, installed_path, command, and path_hint. Run --version through the exact returned command and confirm 0.7.3 or later. If the command directory is not on PATH, keep using that absolute command; do not guess the installation path or edit PATH automatically.

Stop on a digest mismatch

CLI_DIGEST_MISMATCH means the file does not match the version bound by the Skill. Delete only the temporary file downloaded for this attempt and obtain a new trusted prompt from the website. Do not ignore validation, change the expected digest, or continue executing the file.

First-run discovery

oasn-sa-dev --version
oasn-sa-dev auth status
oasn-sa-dev doctor
oasn-sa-dev portal commands

doctor is read-only. It reports the Python version, SSH and ssh-keygen availability, loopback availability, and any discovered public-key path. portal commands lists the current allow-listed website operations and related non-portal commands without contacting an arbitrary endpoint.

Only if an SSH connection is required, no existing key is available, and the developer explicitly approves creating a new key, run:

oasn-sa-dev ssh-key ensure --create

To create a new key at a specific location:

oasn-sa-dev ssh-key ensure --create --path <new-private-key-path>

--path names the private-key target without a .pub suffix. The CLI generates the corresponding public key and refuses to overwrite either an existing private or public key. It sends only the public key to the platform and never reads or uploads private-key contents.

Select a source before creating a Workspace

oasn-sa-dev workspace sources --version-id <agent_version_id>

The agent_version_id must come from the trusted website prompt. Show the returned options and obtain an explicit choice:

• reuse existing_workspace and preserve its current files;
• create from a particular restorable published version; or
• use --fresh to start from the platform base environment.

recommended_source_version_id is only a recommendation. It does not authorize the local AI to choose a source. The source Version ID supplies a saved compatible snapshot; it never replaces the target draft's agent_version_id.

Create and query a Workspace

# Restore from an explicitly selected version snapshot
oasn-sa-dev workspace create --version-id <agent_version_id> --source-version-id <source_version_id>

# Start from the platform base environment after an explicit fresh choice
oasn-sa-dev workspace create --version-id <agent_version_id> --fresh

Creation uses browser OAuth when required and polls until ready, terminal, or timed out. It creates a Workspace without prebinding a local SSH key. If an active Workspace already exists, reuse it as selected; do not call workspace create to overwrite it or silently switch its source.

If creation returns:

WORKSPACE_TIMEOUT: workspace_id=<id> last_status=<status>

Preserve that workspace_id and continue querying the same resource:

oasn-sa-dev workspace status --workspace-id <workspace_id>

A timeout is not a failed creation

Do not run workspace create again as a retry. workspace status is read-only and waits on the original Workspace. Only active is usable. failed, closed, published, cleanup_pending, and close_pending are not ready development states.

Bind and verify SSH

oasn-sa-dev workspace connect --workspace-id <workspace_id>

workspace connect is distinct from the read-only status command. It verifies that the chosen private and public key match, queries the binding, binds the public key for an unbound Workspace, verifies the OpenSSH fingerprint for a bound Workspace, renews an expired connection when necessary, and runs a real BatchMode SSH probe. It uses a Workspace-specific known_hosts file, performs first-use TOFU for the dynamic endpoint, and does not alter the user's global ~/.ssh/known_hosts.

A successful result resembles:

{
  "workspace_id": "dws_example",
  "version_id": "sav_example",
  "source_version_id": "sav_source_or_null",
  "status": "active",
  "revision": 1,
  "remote_project_dir": "/oasn",
  "openclaw_version": "2026.6.11",
  "managed_model_capabilities": ["chat"],
  "paid_api_mcp_status": "active",
  "paid_api_mcp_url": "https://example.invalid/mcp",
  "webchat_url": "https://example.invalid/webchat",
  "webui_urls": [],
  "connection_status": "ready",
  "ssh_binding_status": "bound",
  "ssh_verified": true,
  "ssh_command": "ssh -vvv ...",
  "scp_command": "scp ...",
  "expires_at": "2026-09-14T12:00:00Z",
  "failure_code": null
}

All values are redacted examples. Hosts, ports, expiration times, and WebUI links are dynamic. Use the complete commands and URLs from the current result. Do not execute an SSH string from workspace status; connect only after workspace connect returns ssh_binding_status=bound and ssh_verified=true.

Resume an expired connection

oasn-sa-dev workspace resume --workspace-id <workspace_id>

Use workspace resume only after the developer explicitly asks to continue using the same active Workspace and its short-lived connection is expired. It renews that Workspace and its stable Gateway session; it does not create a Sandbox, change the source, bind or replace an SSH key, or verify SSH. Run workspace connect when SSH access is required.

Configure WebUI ports

The OpenAgent website currently has no WebUI-port form. CLI 0.7.3 is the public configuration surface:

# Read the current declaration and proxy state
oasn-sa-dev version webui-ports get --version-id <agent_version_id>

# Replace the complete ordered list (this is not an append operation)
oasn-sa-dev version webui-ports set --version-id <agent_version_id> --ports 7860,8765

# Explicitly remove all business WebUI ports
oasn-sa-dev version webui-ports set --version-id <agent_version_id> --clear

# Keep all ports but create a new generation of links
oasn-sa-dev version webui-ports refresh --version-id <agent_version_id>

• Ports must be unique integers in 1..65535. Ports 22, 18789, and 18790 are reserved.
• The business service must listen on 0.0.0.0:<port>. The platform does not start or stop that process and does not prescribe a start script or health path.
• With no Workspace, set only saves the declaration. With an active Workspace, it synchronizes the mapping in place without rebuilding the Sandbox; code, files, SSH, and WebChat remain in place.
• sync_status=ready means only that the desired declaration finished synchronizing. proxy_status=ready independently means the returned webui_urls passed current session and target-metadata checks. Neither status proves that the business HTTP service is healthy.
• If proxy_status is expired, revoked, pending, unavailable, or not_configured, do not deliver a cached URL as current.
• Setting the already-saved port list is an idempotent no-op, not a link refresh. Use refresh only after explicit authorization to issue a new link generation while retaining every configured port.
• After a port change or refresh, old links are invalid. Query and verify the new URLs. A command timeout or revision conflict requires get and a fresh decision, not an automatic replay.

Authentication state and logout

oasn-sa-dev auth status
oasn-sa-dev auth login
oasn-sa-dev auth logout

• auth status reads cached state without initiating login and may report authenticated or login_required.
• Commands requiring access open browser OAuth when there is no valid session. auth login is an explicit retry after a credential-store or login problem has been corrected; it is not required before every operation.
• An unexpired session is cached only in macOS Keychain, Windows Credential Manager, or Linux Secret Service.
• If a secure credential store is unavailable, the CLI does not cache the session and does not fall back to plaintext config.json, environment variables, or command arguments.
• auth logout attempts server-side revocation and removes the local entry. Inspect server_status; do not treat unconfirmed as confirmed revocation.

Command overview for 0.7.3

workspace sources, create, status, resume, connect, and all three webui-ports operations accept these bounded wait options:

Portal operation families

Run oasn-sa-dev portal commands for the exact current list and oasn-sa-dev portal <operation> --help for parameters. CLI 0.7.3 includes these families:

• session, category, Agent, version, model, resource, cost, readiness, metrics, Publish Job, and Sandbox queries;
• Agent and draft creation, draft export/save, model/resource save, MOM/image upload, publication, supply-state change, version suspension, rollback, context reset, and skill-link operations;
• Codex launch-link generation and bounded website asset download to a new system-temporary file; and
• account, which is listed but currently returns PORTAL_ENDPOINT_UNAVAILABLE because its backend is not implemented.

All non-query portal operations require --confirm after the developer authorizes that exact action. Operations that create or change a business object may also require a stable --idempotency-key, the original quoted --if-match ETag, or a bounded JSON --body-file. Reuse the same idempotency key for recovery of the same intent; use a new key only for a genuinely new intent. Never pass a browser Cookie, token, arbitrary URL, HTTP method, or custom base address.

Operations that are still not public CLI features

Common errors

After a verified connection, continue with Build the Program and Safely Synchronize Files. For business ports and final page output, see Input, Output, and WebUI.