Revyl Workspace

Revyl Workspace

Use the connected Revyl tools for workspace data and device sessions. This workflow does not need a shell. Check the tools actually available in the host; never invent a tool or silently fall back to a shell command. If the connection is absent or expired, ask the user to connect Revyl through the host's normal authentication flow. Never request API keys, passwords, or login codes in chat.

Choose one execution path

• For Atlas or a viewer, use this workflow. Opening a view is not authorization to provision a device, build an app, or run a test.
• For an existing test, use the connected test tools when available; no shell is needed to run a saved test against a known build.
• For a new app, standalone remote build, new persisted test, exploration, or other CLI operation, use revyl-cloud-app in a shell-capable cloud workspace.
• For a continuous development loop in an existing repository, use the bundled revyl-codex-dev-loop skill in a shell-capable host.
• For exact-SHA proof of an existing CI artifact, use the bundled revyl-codex-proof-ci skill and its bounded artifact lookup.

The CLI and MCP can display the same server-issued session ID, but one workflow must own its creation and cleanup. Never call start_device_session to recreate a CLI-owned session just to embed its viewer. Account mismatches require the correct account connection, not a replacement session or a copied credential.

Open Atlas or an existing device

Call open_revyl_workspace with view="atlas" and a known authorized app_id. When no app is selected, use empty arguments to open the Atlas app picker. Do not guess an identifier or use a URL in an identifier field.

For a device, reuse a session ID from the current workflow or resolve an exact session with list_device_sessions. Call open_revyl_workspace with view="device" and session_id. With no session selected, the device view opens the session list; it does not start a new device. If several sessions match, ask which one instead of choosing arbitrarily.

The tool links a client-rendered UI resource. A returned URL is not proof that the iframe loaded, and the absence of an image in the text response is not proof that embedding failed. Report the confirmed tool outcome without claiming to see the live UI. Use a normal viewer link as the fallback when the host cannot render the component. Never publish or share the session merely to make embedding work. In ChatGPT, present the returned chatgpt_url as an Open in ChatGPT link. Clicking it navigates the persistent panel to the selected view; another tool call alone need not update an already-open panel. Do not invent this link when it is absent. Keep workspace_url as the ordinary browser fallback. Say that the view is ready to open, not that it is already visible or playing, unless separate evidence confirms that outcome.

Start a device only when requested

Require an authorized app, environment, platform, and device operation. Resolve the target from the user's request and available read-only tools; ask when it is ambiguous. Supply one artifact selector to start_device_session: a known build_version_id for a pinned artifact, or app_id for the expressly selected app's latest build. Use no_open=true so the client owns viewer navigation and set a bounded idle_timeout, normally 900 seconds.

Record the returned session ID and index. Open that same session's workspace when needed; do not invoke startup again to retry UI rendering. If startup times out, inspect list_device_sessions before considering another start. Never automatically retry an ambiguous provisioning result.

When the request includes a later test against the same build, resolve the latest compatible build once with the available build-list tool and retain its build version ID before startup. Pin both the session and the test to that ID; do not resolve "latest" again between operations.

Pass the server-issued session_id to every session-scoped tool that declares it. For an older tool accepting only session_index, first confirm that the index still maps to the intended ID. Use the tool's declared arguments for screenshots, interactions, and validation. Inspect returned screenshots before describing them, and treat missing or false validation results as unverified or failed.

For a bounded app walkthrough, use screenshots and the declared interaction tools on that same session. Respect the authorized action/time budget and avoid destructive or externally visible actions unless separately authorized. Separate observed failures, usability judgments, and measured timings.

To run an explicitly requested existing test, resolve its exact name or ID. Use manage_tests(action="run", params={test_name, build_version_id}) in the core/full profiles, or run_test when that tool is exposed. Inspect the returned status and poll the declared status tool within a bound when necessary; a queued execution is not a passing test. A test execution owns its own device lifecycle and does not reuse the manual session. Do not create or change a test as a fallback when the named test is missing.

When the authorized work ends, stop only the owned session with stop_device_session(session_id=...); for an older index-only tool, recheck the ID-to-index mapping first. Never set all=true. A successful request to stop is not the same as a released device: check the terminal result and the active-session list. Use bounded polling, and report pending cleanup without claiming that it completed.

Do not create, modify, or publish tests, builds, workflows, shares, or reports unless the user requested that particular action. Keep signed media URLs, launch values, credentials, and customer content out of public artifacts.