---
title: "How to create your first Cloud Agent on TOSE"
description: "Deploy a Cloud Agent on TOSE: pick an agent, set CPU, RAM, disk and repositories, approve the plan, add your API key and open the console."
url: https://tose.sh/en/blog/create-your-first-cloud-agent
lang: en
category: "Guides"
tags: ["cloud-agents", "guide", "claude-code", "codex", "pi"]
author: "TOSE"
published: 2026-11-13T12:49:36.462341Z
updated: 2026-11-13T12:49:36.462402Z
---

# How to create your first Cloud Agent on TOSE

**TL;DR:** You need a workspace with a funded prepaid wallet, the owner or admin role, and a model provider API key. Cloud Agents → pick an agent → deploy → configure → Review the plan → Approve plan → add your key → Open agent. Disks can grow but never shrink, so start with the smallest size.

> **info**
> **Cloud Agents on TOSE series** · Part 2 of 5
> 1. [Introduction](/en/blog/introducing-cloud-agents-on-tose) · 2. **Create your first Cloud Agent** (this article) · 3. [Delegate tasks via MCP](/en/blog/delegate-tasks-to-cloud-agents-via-mcp) · 4. [GitHub and pull requests](/en/blog/cloud-agents-github-pull-requests) · 5. [Pricing and auto-sleep](/en/blog/cloud-agent-pricing-and-auto-sleep)

[Video: Create your first Cloud Agent](https://cdn.tose.sh/blog/bd3a75da0f4b9108b4f8a4627cb11d37.mp4)

[Part 1](/en/blog/introducing-cloud-agents-on-tose) explains when to delegate to a Cloud Agent. This guide walks through setting up your first one.

## Before you start

• A TOSE workspace with a **funded prepaid wallet**. Agents bill compute per hour and storage per month.

• The **owner or admin** role in the workspace.

• A **provider API key**: `ANTHROPIC_API_KEY` for Claude Code, `OPENAI_API_KEY` for Codex, `PI_API_KEY` for Pi. Claude Code can also use a Claude plan (Pro or Max) instead of an API key, signed in after deploy or with `/login` in the console.

TOSE does not charge for model usage; the provider bills tokens just as it would on your laptop.

## Step 1: Pick an agent

In the dashboard, open **Cloud Agents**. The workspace's agents are at the top, and **Available agents** below lists Claude Code, Codex and Pi. Pick one and start the deploy.

![The Cloud Agents page](https://cdn.tose.sh/blog/fa39d79e190d68cef99f674e4523d890.webp)

*Mockup of the Cloud Agents page with sample data.*

## Step 2: Configure

![The agent configuration form](https://cdn.tose.sh/blog/09ecca36d9d51da6afa22f8df06fcb8b.webp)

*Mockup of the configuration form with sample data.*

**App name.** Use a name that reflects the job, for example `codex-dashboard`.

**Provider and model.** Choose the model the agent will use.

**CPU and RAM.**

| Agent | CPU | RAM |
| --- | --- | --- |
| Claude Code, Codex | 1, 2 or 4 cores | 2, 4 or 8 GiB |
| Pi | 1 or 2 cores | 1, 2 or 4 GiB |

*CPU and RAM.*

The smallest size handles most code changes. Size up for heavy builds or large test suites.

**Workspace disk.** `/workspace` comes in 5 GiB (default), 10, 20 or 50 GiB, plus 1 GiB for `/home/agent`. **Disks can grow but never shrink**, so start small.

**Repositories.** Attach up to 10 GitHub repositories through the workspace's GitHub App. Access is read-only by default. See [part 4](/en/blog/cloud-agents-github-pull-requests) to enable push and pull requests.

**Auto-sleep.** Off by default. We suggest 30 minutes for a first agent. See [part 5](/en/blog/cloud-agent-pricing-and-auto-sleep).

**Network.** The agent can reach the public internet. Private, link-local and metadata addresses are blocked.

## Step 3: Review and approve the plan

Click **Review the plan**. Nothing is created yet; TOSE builds a plan listing the resources, the hourly compute ceiling, the monthly storage price and any blockers.

![The plan review screen](https://cdn.tose.sh/blog/f9c0e4717233b0b0b6819702fda357b8.webp)

*Mockup of the plan screen with sample data.*

If everything looks right, click **Approve plan**. A plan runs only after a person approves it, even when another AI created it over MCP.

## Step 4: Install and add your key

At the install step, enter your provider API key. The key is encrypted and used only by the agent; it never needs to live in a repository or a `.env` file.

## Step 5: Open the agent

When the install finishes, click **Open agent**. The agent page has five tabs: **Overview, Tasks, Repositories, Settings, Activity**.

![The agent overview page](https://cdn.tose.sh/blog/cb7908b0bd459b08f52e7524b6a0c027.webp)

*Mockup of the agent page with sample data.*

The console runs in the browser and is private: it has no public address, and only workspace owners and admins can open it.

## Run a small first task

Start with something you can verify in a few minutes:

```
Read the README and the repository layout.
Run the existing test suite and list any failing tests.
Do not change any files.
```

If the agent does this and reports accurately, it is ready for real work.

## Good to know

• **No in-place upgrades.** When a new release ships, install it as a new agent and move your work over with git.

• **Delegating over MCP** needs a release with task support: Claude Code 1.1.0, Codex 1.1.0 or Pi 1.2.0.

• **A sleeping agent keeps its files and provider sign-in** but loses its tmux session. Wake it with **Wake and open**.

**Previous:** [← Introducing Cloud Agents](/en/blog/introducing-cloud-agents-on-tose) **Next:** [Delegate tasks to Cloud Agents via MCP →](/en/blog/delegate-tasks-to-cloud-agents-via-mcp)

## FAQ

### What do I need to create a Cloud Agent on TOSE?

A workspace with a funded prepaid wallet, the owner or admin role, and an API key from the model provider.

### Can I shrink the disk after creating the agent?

No. The /workspace disk can only grow, so start with 5 GiB.

### How do I upgrade an agent to a new release?

TOSE does not upgrade in place. Install the new release as a new agent and move your work over with git.
