Reuse a setup with Cloud agents

A Cloud agent is a saved setup for new workspaces: which repository to clone, what the agent should know, which model to use, how big the machine is, and which tools it has. Start as many workspaces from it as you like. Each one gets its own machine, files and chats.

Saving a Cloud agent starts nothing and costs nothing. Only the workspaces you start from it do.

Create one

Open Cloud agents in the sidebar and choose Create agent.
Give it an Agent name and, if you like, a Description.
Open each section and fill in what you need. Every section is optional:

Section	What you set
Behaviour	Instructions the agent gets at the start of every chat, the Default model and the Reasoning effort
Repository and SSH	The Git repository to clone, a Branch or tag, and the SSH known hosts for your Git host
Machine	The Compute size, Disk (GB) and the Idle timeout (minutes) before it sleeps
Environment and setup	Environment variables for secrets and settings, and a Startup command that runs on every boot
MCP, agents, skills and permissions	MCP servers, custom agents, skills and permission rules, as JSON

Choose Create agent.

Private repositories

After you save, the agent shows an SSH public key. Add it to your repository as a deploy key once. Every workspace you start from this agent can then clone it.

Start a workspace from it

On Home, pick the agent under Start from, describe the task and press Enter.
Or, in Cloud agents, choose Start workspace on the agent.
To change a setting for this one workspace before it boots, choose Customize and start instead.

The workspace copies the agent's settings when it starts. Later changes in its Workspace settings never touch the agent.

Edit, copy or delete an agent

Open the agent in Cloud agents to edit it. Edits apply to workspaces you start afterwards. Workspaces that already exist keep the settings they started with.

Duplicate, in the agent's menu, makes a copy to change. Environment variables are not copied: enter them again in the copy.

Deleting an agent keeps every workspace started from it, with their files and chats.

Turn a workspace into an agent

Set up a workspace by hand until it works the way you want. Then open Workspace settings and, under Reuse, choose Save as Cloud agent. Cloud generates a new deploy key for the agent. Choose Also copy encrypted environment variables to bring your secrets along.

Tips

Keep the startup command safe to run twice. It runs on every boot, not only the first. Check whether a dependency is installed before installing it.
Put secrets in environment variables, not in instructions or MCP settings. In MCP settings, refer to a secret as ${VARIABLE}. Saved values are encrypted and never shown again.
Install large tools with the startup command. The JSON configuration is limited to 64 KiB.

From the terminal

haarness cloud agent list
haarness cloud agent show AGENT_ID
haarness cloud workspace create --agent AGENT_ID --title "Nightly review"