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

# Cloud workspaces

A Cloud workspace is a machine of your own that runs the Haarness agent. It has your repository, a persistent disk, a
terminal and as many chats as you like. It keeps working after you close the tab, and it goes to sleep on its own
when there is nothing to do.

## Start a workspace from a task

1. Open **Home**. It is the first page after you sign in.
2. Describe the task, for example "Find why the login test fails and fix it".
3. Press Enter, or choose **Start workspace**.

Cloud names the workspace after your task, opens it, and sends the task as soon as the machine is ready, usually in
under a minute.

Under the box you can change three things before you start:

| Option | Use it to |
| --- | --- |
| **Start from** | Begin from a [Cloud agent](https://haarness.ai/docs/cloud/agents.md) you saved, with its repository, instructions and tools |
| **Machine** | Pick a bigger machine for heavy builds. See [compute rates](https://haarness.ai/docs/cloud/compute-storage-egress.md#compute-hours) |
| **Model** | Choose the model. **Router default** lets the router pick |

Choose **Advanced** to set everything else before the first boot: the repository, disk size, environment variables
and a startup command. A new workspace gets a 5 GB disk unless you choose another size there.

> **Plan full?** Your plan sets how many workspaces can run at once and how much disk they may use in total. When
> either is full, **Home** offers to send the task to a workspace you already have instead. Otherwise stop or delete
> a workspace first, or turn on **Overage** in **Billing** to pay for extra disk.

## Work in a workspace

The workspace page is a chat with the agent. Approve or deny actions when it asks, and the answer streams in.

- **Chats:** one workspace can hold many chats, listed beside the conversation (on a narrow screen, open
  **Show chats**). Choose **New chat** to start another. All chats share the same machine and files.
- **Model and agent:** change them for the next message with the pickers under the message box.
- **Attach files:** drag them into the message box or use **Attach files**.
- **Workspace tools:** open the panel on the right for:

| Tab | What it is for |
| --- | --- |
| **Files** | Browse, edit, upload, download and create files on the workspace's disk |
| **Terminal** | A shell on the machine |
| **Changes** | Review what the agent changed |
| **Tasks** | Follow background work the agent started |
| **Capabilities** | Turn skills, agents, MCP servers and plugins on or off, or install them from the [Marketplace](https://haarness.ai/docs/cloud/marketplace.md) |

## Leave it running, come back later

Close the tab whenever you like: the agent finishes what it is doing. Open the workspace again from **Workspaces**, from
Desktop or from the terminal.

When nothing has happened for 10 minutes (the workspace's **Idle timeout**), the workspace falls asleep. Its compute
stops, and its files, chats and installed tools stay on its disk. When you open it, the chat says **This workspace fell
asleep. Send a message to wake it.** Your message wakes it and goes to the agent as soon as it is up. **Wake** in the
workspace menu wakes it without a message, and a [scheduled prompt](https://haarness.ai/docs/cloud/schedules.md) wakes it by itself.

A running answer and an open terminal both count as activity. When you are done with a terminal, close it from
the **Terminal** tab so the workspace can sleep.

## Use a private repository

A workspace clones over SSH with a deploy key that Cloud generates for it. Add that key to your Git host before
the workspace boots for the first time:

1. On **Home**, choose **Advanced**.
2. Set the **Git repository** (for example `git@github.com:acme/app.git`) and, if you want, a **Branch or tag**.
3. Paste your Git host's **SSH known hosts** entries, for example the output of `ssh-keyscan github.com`.
4. Select **Create it asleep (set up SSH access before it starts)**, then choose **Create workspace**.
5. Open **Workspace settings** from the workspace menu and copy the **SSH public key**.
6. Add it to the repository as a deploy key, with write access if the agent should push.
7. Go back to the workspace and choose **Wake** in the workspace menu.

The private half of the key never leaves Cloud and is never shown.

> **Using the same repository often?** Save it once in a [Cloud agent](https://haarness.ai/docs/cloud/agents.md). You add the agent's
> deploy key to your Git host once, and every workspace you start from it can clone straight away.

## Change a workspace's settings

Open the workspace menu and choose **Workspace settings** to change its instructions, default model, machine size,
idle timeout, environment variables, startup command, MCP servers, agents, skills and permissions.

- Saving a running workspace restarts it. Files and chats are kept.
- The repository, region and disk size are fixed when the workspace is created. To change them, start a new workspace.
- **Save as Cloud agent**, under **Reuse**, turns these settings into a reusable template.

Environment variables are encrypted and never shown again after you save. To change one, enter the full set again.

## Put to sleep, wake or delete

All three are in the workspace menu:

| Action | Compute | Files and chats | Use it when |
| --- | --- | --- | --- |
| **Put to sleep** | Stops | Kept | You are done for now and do not want to wait for the idle timeout |
| **Wake** | Starts | Kept | You want it running before you send anything |
| **Delete workspace** | Stops | **Deleted for good** | You no longer need anything on it |

There is no archive: a workspace you no longer need is deleted, which is also what frees its disk. A sleeping workspace
still uses disk, which counts toward your plan's disk allowance. Open terminals end when a workspace falls asleep.
**Rename workspace** is in the same menu.

If your account has no plan and no purchased credits, a workspace that has been asleep for 30 days is deleted with
its disk. See [Cancel](https://haarness.ai/docs/cloud/resets-and-cancellation.md#cancel).

## Keep a copy of a workspace's files

- **Push to Git.** For a repository, ask the agent to commit and push its work, or do it in the **Terminal** tab.
- **Download files** from the **Files** tab.

Downloading a whole workspace's disk in one archive is not available for Cloud workspaces. Copy what you need before
you delete a workspace: deleting erases its disk.

## From Desktop and the terminal

Your Cloud workspaces are also in Desktop, under **Cloud workspaces**, and in the CLI:

```sh
haarness login
haarness cloud workspace list
haarness cloud workspace create --title "Investigate issue"
haarness cloud workspace attach WORKSPACE_ID
haarness cloud workspace stop WORKSPACE_ID     # puts it to sleep
haarness cloud workspace start WORKSPACE_ID    # wakes it
```

`attach` opens the workspace in the terminal UI. See [Automate with the CLI and SDKs](https://haarness.ai/docs/cloud/cli-and-sdk.md).

## What does a workspace cost?

A workspace uses **compute hours** while it runs and **disk** while it exists. Model requests use **AI credits**.
A sleeping workspace uses no compute. See [Compute, storage and egress](https://haarness.ai/docs/cloud/compute-storage-egress.md).