Cloud Environment

View saved version →

---
name: cloud-desktop
description: Use in a managed Codex Cloud chat to open a URL in shared Chrome, inspect a Linux app, show the Desktop panel, or diagnose missing computer-use tools.
---

# Use the shared cloud desktop

When the chat’s environment context identifies a managed cloud executor, use
its Chrome for “open this URL” or “check in the browser” unless the user
names another browser or device.

Chrome and native apps share one Linux display (X11). Codex can use the
computer-use tools with the Desktop panel closed. Opening the panel lets the
user watch and take control of the same screen. Closing it disconnects the
viewer and leaves the desktop running.

## What starts on demand

On an on-demand desktop, Codex can discover the tools and check status while
the display stays asleep. The first valid desktop `js` call starts the display
before running the code. Connecting the Desktop viewer also starts it.
Chrome has its own startup setting. When configured to start closed, it
launches on the first browser operation that needs it, such as opening a tab.

## Open and inspect

Look for the desktop JavaScript tool (usually `cua_repl.js`) among the tools
offered directly to this turn. Follow its first-call instructions. For a new
tab in Chrome, `await cua.createBrowserTab("cdp", url)` can be the first
action when offered, even with the panel closed.
Use `await cua.getState()` to discover available browsers and apps. For an
existing tab, follow the runtime’s tab-selection or claiming instructions.
Inspect the page before reporting what loaded. Use Sky for native windows
or a full-screen screenshot when available.

## Show the user

When the user asks to watch or needs to act, such as completing sign-in, call
`open_in_codex({"target":{"type":"cloud-desktop"}})` if offered. In supported
Codex desktop chats, the user can also open the right side panel and choose
**New tab (+) → Desktop**. Let the user **Take over** and select **Return
control** when finished. Pause agent input during the handoff, then inspect
the same page before continuing.

## If control is unavailable

Call `cloud_environment.environment_status({})` and match its `environment_id`
to the selected executor. Check `capabilities[].remote_desktop`. A cold desktop
can report `enabled: true` with `state: unknown`. If the environment is
starting, recheck the tools once it is ready. Report the environment ID,
desktop status, and which tool was missing or which call failed. Say what
you could verify. If only the viewer works, offer to open it for the user.

View saved version →

---
name: cloud-environment-runtime
description: Read at the start of work in a managed cloud environment. Run browser tests, take screenshots, and record video; install development dependencies; inspect network policy and configured credentials; build and run Docker containers with the session proxy and CA trust; use Tailscale VPN access, configure TCP forwarding, and diagnose access failures.
---

Read this skill at the start of work in a managed cloud environment, including
resumed work. Use `cloud_environment.environment_status` to inspect the attached
environment's configuration, capabilities, and observed readiness. Call it with
`{}`; the runtime selects the environment for this thread. Confirm the returned
`environment_id` identifies the executor you are using; the result does not
describe other attached executors or unapplied draft changes. If no managed
environment is attached, do not reuse an environment ID from an earlier turn.

## Onboarding and normal threads

In onboarding threads, collaborate with the user on the reusable configuration.
Identify required domains, credentials, packages, and repositories, and prepare
draft changes with the onboarding tools. Ask the user to review domain additions
and enter secret values in environment settings. Continue independent setup and
validation while they review.

The model saves draft proposals; the user reviews them in environment settings.
**Save draft** can request changes to the running onboarding environment.
**Publish** makes the saved configuration and prepared environment snapshot
available for future tasks. Use these actions when the product enables them;
publication waits for an idle setup chat, completed review and required settings,
and completion of any necessary save. After saving, refresh status and validate
changed access with a fresh connection before relying on the new configuration.

If a task is blocked and `cloud_environment.request_changes` is available,
omit `environment_id` for the current instance or pass the ID of another
managed instance selected on this thread. Explain the blocker. Supply a category
only if you know its complete intended contents. If you cannot identify entries
that must be kept, ask the user before proposing a replacement. Use existing
vault references for credentials. Never ask for secret values in chat.
For a network credential, its allowed domains control where the credential
can be sent. The network policy must also permit the destination.
After approval, retry the blocked operation on the selected instance with a
fresh connection or process. For the default instance, check the observed
revision, failure, and relevant readiness state with `cloud_environment.environment_status`.

For changes to the reusable configuration, or when this tool is unavailable,
use the onboarding/settings flow. Future tasks can select the published version.

## Runtime context

Before installing development dependencies, read
[Package installation](references/packages.md). Before building or running Docker
containers, read [Docker in Docker](references/docker.md).

For ordinary HTTP(S), run the client in the default agent sandbox with its
inherited proxy variables and CA trust. For example, run curl against the
destination URL without a proxy flag. If the command cannot connect to the
inherited proxy, request approval to retry the same command outside the sandbox
with `sandbox_permissions="require_escalated"`. The Cloud proxy still enforces
destination policy. If it explicitly denies the destination, use the environment
change flow described above.

Direct connections to the Cloud sidecar
(`proxy:8080`, `proxy:8088`, or the status endpoint at `proxy:8099`) require
an approved agent command outside bubblewrap.

Before network or credential work, read
[Cloud environment networking](references/networking.md) and inspect the selected
executor's `/etc/codex/network-policy.json` for its startup settings. Read
[Tailscale VPN access](references/vpn.md) w

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.