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.
Part 1 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.

Step 2: Configure

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 |
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 to enable push and pull requests.
Auto-sleep. Off by default. We suggest 30 minutes for a first agent. See part 5.
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.

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 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 Next: Delegate tasks to Cloud Agents via MCP →
Frequently asked questions
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.