> ## Documentation Index
> Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Cloud environment

> Prepare Cloud in the background and connect your account when Cogno needs your action.

Your Workspace shares one Cloud environment for Cloud Projects. Cogno can keep
working there while your computer is off. Check preparation and account
connections in **Settings → Cloud**.

Cloud Projects use this shared environment. Local folder connection notices apply
only to Local Projects. The computers list in **Settings → Machines** lists your
Local and remote computers; the shared Cloud environment is in **Settings → Cloud**.

## Prerequisites

Your Workspace must support Cloud environment creation. Creating an environment
or retrying its creation requires permission to update the Workspace.

Creating a new Cloud environment requires the Business plan. On the Free plan,
the **Cloud environment** step offers **Upgrade to Business** if you can manage
billing, and otherwise says the Business plan is required. An environment that
already exists keeps working if the Workspace later returns to the Free plan.

## Prepare Cloud in the background

In deployments with Cloudflare Cloud execution enabled, confirming a
Business subscription starts Cloud preparation automatically. Keep working or
close the page; preparation continues in the background. An explicitly stopped
or deleted environment is not restarted by a billing update.

Open **Settings → Cloud** to check **All Projects**. Local Projects remain on
their computers. **Your account** shows your own Codex and Claude connections.
Select **Connect** beside the account you want to use for Cloud work. This same
connection is available from any Project's settings, including Local Projects.

| Status | Meaning |
| - | - |
| **Preparing your Cloud** | The environment or repository copies are being prepared. |
| **Connection needed** | A member needs to connect an account for Cloud work. |
| **Connected** | An account connection is saved; this status does not verify its current provider session. |
| **Code and connections are ready** | Repository copies and saved account connections are present. |
| **Some Projects need attention** | Check repository access or Project ownership for the affected Project. |

> [!NOTE]
>
> Setup status does not confirm that Project-specific dependencies are installed
> or that a Task has run successfully. Runtime access is checked when work starts.

## Create the environment manually

Manual creation remains available where automatic setup is not used, including
after deleting an environment. Business Workspaces waiting for automatic setup
show preparation progress instead of a separate creation step.

**Settings → Cloud** shows setup as two connected steps: **Cloud environment**,
then **Cloud Project**. A check mark means the step is done; the next step has
the one button to press. Selecting **Create in Cloud** from the Project creation
menu before an environment exists brings you here.

**1. Cloud environment**

Select **Create**. The step shows **Creating** with a spinner while the
environment is set up. This takes a few minutes; you can leave the page and
creation continues. On the Free plan the step offers **Upgrade to Business**
instead.

**2. Cloud Project**

Once the environment is done, select **Create** on this step. If you came
from **Create in Cloud**, Cogno continues to Project creation on its own.
Your Cloud Projects are listed under the step; **Add** creates another.

Below the steps, a map shows your Workspace: **Member computers** and **Cloud**,
each with the Projects that run there and their repositories. Cloud is drawn
as a dashed outline until its environment is ready.

If creation fails, the first step shows the reason and **Retry**. For
infrastructure failures, ask your Workspace administrator to check the execution
infrastructure before retrying. **Delete Cloud environment** sits below the steps
once an environment exists.

> [!NOTE]
>
> A finished first step confirms that the environment exists. It starts when
> work arrives, so it is not necessarily running right now.

## Connect your Cloud account

Cloud Project creation requires Cloud execution to be enabled for the deployment.

**1. Create a Cloud Project**

Select **Create in Cloud** from the Project creation menu. Choose repositories,
enter the **Project name**, and select **Create Project**. Your Project is saved
before account connection starts.

**2. Wait for sign-in**

**Connect Codex** starts the Cloud environment automatically. Startup can take
a few minutes. If your account is already connected, Cogno opens your Project.

**3. Complete Codex sign-in**

The OpenAI sign-in page opens in another tab. Enter the **Device code** shown
in Cogno there. If the tab did not open, select **Open Codex sign-in**.
Keep the Cogno page open; it checks completion and returns to your Project.

Selecting repositories saves the Project's requirements. Cogno prepares their
working copies when a Task starts. Project creation and account sign-in do not
clone repositories.

Members with write access and account connection permission can connect their
own account; Project ownership is not required. Open **Settings → Cloud** or a
Project's settings and select **Connect** beside Claude or Codex under
**Your account**. Both places save the same personal connection. Claude opens a separate
sign-in tab; paste its code into **Authorization code** in Cogno and select
**Complete connection**.

When you open a Cloud Project as its Owner, Cogno checks your selected Claude or
Codex connection. If the environment is stopped, opening the Project starts it
and waits for readiness. **Reconnect account** appears when the saved sign-in
is missing or rejected. Select it to open the existing connection page.
Opening the Project itself does not start sign-in or change saved credentials.
If the connection cannot be checked, select **Retry**; an unavailable provider
or network does not mean your sign-in has expired.

## Start a Cloud Task

Open your Cloud Project, create a Task, and choose its assignee in the full
form's **How to proceed** panel. Select **Watch it get built** to start execution,
or **Plan it first** for a plan-only run.

Both assigning yourself and assigning another member use the Project's Cloud
environment. Cogno selects a connected member: the Task assignee first, then its
previous Cloud runner, then the member with the fewest Cloud runs in the last
seven days. A run keeps its selected member and provider. Work waits when no
member has a connection. Starting from the browser does not require opening Desktop or
selecting a Local Environment.

Cogno checks the Project's execution location before enabling these two start
actions. If that check fails, select **Retry**. **Later** saves to Backlog, and
**Create** saves without starting execution.

Before the coding agent starts, Cogno prepares the Project's repository working
copies. Preparation can take up to five minutes. If preparation fails, that run
ends with a failure.

Your Workspace's Cloud environment can run up to three agent runs at the same
time across its Cloud Projects. Cloud Tasks and Project work share this limit.
Additional requests are retried automatically as capacity becomes available.

## Project work in Cloud

Cogno runs work for a Cloud Project in your Workspace’s Cloud environment.
When one mention selects several Projects and includes a Cloud Project, Cogno
keeps one combined agent run and uses the Cloud environment for it.

The run can use context from the selected Projects, but cannot access folders
on members’ Local Machines. If all selected Projects are Local, Cogno keeps
using the Local Machine selection. A missing Cloud environment does not cause
the work to switch to a Local Machine.

New Cloud Tasks and Project runs use full access for commands and file operations,
bounded by the Cloud execution account's operating-system permissions. Plan-only
runs remain read-only. Integration Tool permission settings still apply.

## Tools available to Cloud Tasks

Cloud Tasks can use Cogno tools and the selected runner's eligible integration
connections according to the Workspace's tool permissions, narrowed by any Project tool
permission overrides, the same as other Task runs. Personal
connections still belong to their owner, and existing Project resource filters
continue to apply.

Tools allowed without approval can run. Blocked tools and tools that require
approval cannot run in autonomous Cloud Tasks because they have no approval flow.
Removing permission also blocks subsequent calls from an already running Task.
Its access ends when
that execution completes or is cancelled, or its Cloud environment is interrupted.

## Automatic stop and restart

The Cloud environment checks for inactivity every 15 minutes. It stops only after
all accepted work, account connection attempts, and result saving have finished,
with at least 15 minutes since the last activity. A normal stop is therefore about
15–30 minutes after the last activity, plus processing delay.

New work arriving during shutdown waits for the environment to restart. Stopping
preserves Project files and connected accounts. The next Cloud Task or Project
run starts the environment again.

## Delete the shared Cloud environment

To keep your Workspace and Projects while deleting their shared VM, open
**Settings → Cloud → Delete Cloud environment**. Review the warning and select
**Delete shared VM and disk**. This requires Workspace update permission;
Project ownership alone does not grant it.

> [!WARNING]
>
> Deletion affects every Cloud Project in this Workspace. Running work and Project
> preparation are interrupted. Local repositories, unpushed changes, files, and
> stored Claude Code / Codex sign-ins are lost. Save what you need before deleting.
> Workspace and Project records remain.

Cleanup runs in the background and retries temporary failures. You can leave,
reload, and return to Cloud settings to check it. **Create** becomes available
once removal is confirmed. Create the environment again, then reconnect from
each Cloud Project's **Cloud accounts** settings. Previous files and sign-ins
are not restored. Persistent storage is reclaimed through the infrastructure
provider's deletion policy; the status is not a physical-erasure certificate.

## Delete the Workspace's Cloud environment

When the Workspace owner deletes a group Workspace, Cogno also removes its Cloud
environment. Workspace access ends immediately. Cleanup runs in the background
after Workspace deletion and may take time. Temporary service failures are
retried automatically.

> [!WARNING]
>
> Workspace deletion stops its running Cloud work and deletes the environment's
> persistent storage, including repository working copies and agent state.
> This deletion is irreversible.

## Troubleshooting

### Sign-in did not finish

If startup takes too long or sign-in expires, select **Retry** on the connection
page. Your Project remains saved. You can also return later through the
Project's **Cloud accounts** settings. Provider verification failures are shown
as errors and do not count as successful connections. Known expired sign-ins also
require reconnection before a new Cloud Task can start. Open the Project and
select **Reconnect account**, or use **Cloud accounts** in Project settings.
Reconnecting does not automatically retry a failed Task.

If the Cloud environment itself failed to start, **Settings → Cloud** shows
**Could not start** on the first step, and opening the connection page does not
repeatedly restart it. A Workspace owner or administrator can select **Retry**
there or on the connection page to request a fresh startup after admitted work
has settled; the step shows **Starting** until it is up.
Project ownership alone does not grant recovery permission, and recovery does
not automatically rerun failed Tasks.

While Cloud work is waiting to run, Cogno also requests this recovery on its own,
waiting longer between attempts (from 5 minutes up to hourly) if startup keeps
failing. Without waiting work, a failed environment stays as it is until someone
selects **Retry**.

If Cloud capacity is temporarily full, **Settings → Cloud** shows **Waiting for
Cloud capacity**. This is not a failure: the environment starts automatically
when capacity frees up, and waiting work is delivered then. There is nothing to
retry.

### Cloud work is waiting for a login

Cloud work runs as a Workspace member who has connected a Codex or Claude
account. If nobody in the Workspace has, Cloud work does not start: it waits,
and owners and administrators get an Inbox notification, **Cloud work is
waiting for a login**, at most once a day. Selecting it opens **Settings →
Cloud**.

As soon as a member connects an account there, the waiting work starts on its
own; nothing needs to be asked again. Work that is still waiting after 24 hours
fails with this reason, so ask again once an account is connected.

### Creation status could not be loaded

If creation status cannot be loaded, **Retry** fetches it again. If environment
creation failed, **Retry** requests creation again. Read-only members can view
the status but cannot create or retry creation.

Known creation failure reasons are shown in your interface language. If the reason
is unavailable or unrecognized, the page shows a general creation failure message.

## Related docs

* [Projects](/docs/projects.md)
* [Execution access](/docs/execution-access.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.