Running Cloud Agents
A cloud agent is the same agent as AI Chat, but it works on a copy of your site in the cloud instead of on the project open on your Mac. It reads and edits files, runs checks on its own changes, and keeps all of its work on a separate branch. Your local project isn’t touched.
Use it when you want a task to keep going while your Mac does something else, or when you want to try a change without touching your working copy.
Before you start
Section titled “Before you start”- A paid plan. Cloud agents aren’t available on Free. See the monthly limits below.
- Apple’s command line developer tools, the first time you use this on a new Mac — see Install & Sign In.
- A published site. The project needs to have been published at least once, so it has a site name.
- Owner access. Only a project’s owner can start a cloud agent. The credits come from the account of whoever starts it.
- No attached folders. Folders attached to a chat only exist on your Mac. Remove them before sending the chat to the cloud.
Start a cloud chat
Section titled “Start a cloud chat”- Open AI Chat from the left rail.
- Click the cloud icon (Use cloud agent) next to the composer.
- Describe what you want and send it with Run in cloud.
The agent uses the model selected in the composer’s model dropdown.
Before the first message goes out, Plyed uploads your current local files so the cloud copy starts where you are.
Watch it work
Section titled “Watch it work”Progress streams into the chat just like a local run: each step the agent takes (editing a file, running a check) and its replies. The first message takes a little longer while the workspace starts up. The Cloud list (see below) shows each workspace’s status, for example Provisioning, Running, Idle or Paused.
To stop the current reply, use the composer’s stop control, which is labelled Cancel cloud run for cloud chats. Stopping asks the agent to finish up; wait for the status to change before you send the next message.
Keep the conversation going
Section titled “Keep the conversation going”A cloud chat is a workspace, not a one-off job. Follow-up messages continue in the same workspace, with everything the agent already did still in place.
When nothing has happened for about 20 minutes, the workspace pauses on its own. A paused workspace keeps all its work and costs nothing. Sending another message, or opening its preview, wakes it back up. That can take a moment.
To see all your cloud chats for a project, open the command palette and choose Cloud. The list shows each chat’s status. Click one to reopen it.
Type $ in a cloud chat to attach one of your skills to a
message. The cloud agent uses the same skills you keep on your Mac, once
they’ve synced.
Preview the result
Section titled “Preview the result”Once the workspace’s site is running, the chat shows a Live preview card with an Open button, and the newest one stays pinned just above the message box, so you never have to scroll back for it. It opens the site running inside the workspace, so you can check the agent’s work straight away. The first start can take a few minutes. Treat the address like an unlisted link — don’t share it if you’d rather keep the work-in-progress to yourself — and note that it expires when the workspace ends.
Publish the result
Section titled “Publish the result”When you want something you can share, click Publish, either on the live preview card or next to the chat in the Cloud list. Plyed builds the workspace’s current state into a preview site at:
https://<your-site>--run-<id>.plyed.cloudThat preview is separate from your live site and from your own preview branches. Publishing it never changes what’s live on your site, and it doesn’t count toward your plan’s preview-branch limit. Anyone with the address can open it.
Publishing doesn’t copy the changes into your local project.
Merge the work into your site
Section titled “Merge the work into your site”The agent’s work stays on its own branch until you merge it into main, your
live site’s branch. When the work is done, the agent adds a Merge into
main card to the chat — it can’t merge on its own. Click Merge — update
live site to bring the work in, or merge it later from the Cloud section
of the Git panel, where Compare shows what would change first. See
Branches and Merging.
Archive or end a workspace
Section titled “Archive or end a workspace”Right-click a cloud chat in the chat sidebar:
- Archive pauses the workspace and moves the chat to the archived list. You can unarchive it and carry on later.
- End cloud workspace… saves the workspace’s files to its branch one last time and then deletes the workspace. An ended workspace can’t be resumed, so start a new cloud chat to continue.
From the web dashboard
Section titled “From the web dashboard”You can also start a one-off cloud run in your browser. Sign in at api.plyed.app, open your project, choose Open cloud agents, describe the change and click Start run. The run page streams each step live, shows a Summary of the agent’s final reply when it finishes, and offers Open preview. While a run is going you can cancel it.
Cloud chats you started from the desktop also appear on this page. There you can Stop a reply, Publish, Archive or End workspace.
What it costs
Section titled “What it costs”Cloud agents use your regular AI credits:
- Model usage is charged as the agent works, at the same rates as AI Chat on your Mac.
- Workspace time costs 1 credit per minute while the workspace is awake. Paused time is free.
Each message sets aside a 200-credit hold, which settles to the real cost when the turn finishes. Model usage for a single message stops at 500 credits. The final save when you end a workspace is free. The full rules are in Plans & Credits.
What the workspace can reach
Section titled “What the workspace can reach”A cloud workspace can install packages from npm and GitHub, load Google Fonts, talk to Sanity, and reach your published Plyed sites. Every other internet address is blocked. A build that fetches from a private API or an unlisted image host will fail in the cloud, even if it works on your Mac. The same goes for MCP servers: cloud agents can’t reach them.
Limits
Section titled “Limits”How many cloud workspaces you can start each month depends on your plan. Follow-up messages in a workspace you already started don’t count toward this limit.
| Plan | Cloud workspaces / month |
|---|---|
| Free | Not available |
| Starter | 20 |
| Pro | 100 |
| Ultra | 500 |
You can have up to 3 cloud runs working at the same time.
Troubleshooting
Section titled “Troubleshooting”| Message | What to do |
|---|---|
| Cloud runs need a paid plan — upgrade in Account to run in the cloud. | Upgrade from Account. Cloud agents aren’t available on Free. |
| Out of AI credits — upgrade in Account. | Your balance can’t cover the 200-credit hold. Wait for your monthly credits, upgrade, or buy a pack. |
| A cloud-run credit hold is still open from a recent run — wait a moment and retry. | An earlier turn is still settling. Try again shortly. |
| Too many cloud runs in flight — wait for one to finish. | Wait for a run to finish, or stop one. |
| Publish this project first — cloud runs need a live site. | Publish the project once, then try again. |
| Remove attached local folders before running this chat in the cloud. | Detach the folder chips from the chat. |
| Cloud runs are temporarily unavailable — try again in a moment. | A temporary problem on our side. Try again shortly. |
| This cloud workspace is ending or has ended. | Start a new chat. Your unsent message stays in the queue. |