Cloud agents

A cloud agent is the same Perch agent you use on Desktop, running in a private cloud workspace instead of on your computer. The workspace has its own files and terminal. It keeps working when you close the tab, quit the app, or put your phone away, and the thread is waiting with the result when you come back.

Start a cloud session

What happens after you send

Your first message starts a private sandbox for the session. A Session line in the thread shows it getting ready, which takes a few seconds. If you send a follow-up shortly after a turn ends, Perch reuses the workspace while it is still warm, so the next turn starts faster.

From there the run streams into the thread: what Perch is thinking, each command it runs, and each file it changes. The thread is live everywhere it is open, so you can start a job on your phone and watch it finish on Desktop.

You can close everything. The run does not depend on any of your devices staying open.

Working on GitHub repositories

The first time you pick a repository, Perch asks you to connect GitHub:

1. Select Connect GitHub in the composer.
2. Perch shows a short code. Select Open GitHub, enter the code, and approve repository access.
3. Once approved, Perch can clone, commit to, and push branches in repositories you can push to.

During a run, Perch works in a clone of the branch you picked and pushes its work to a new branch named perch/ followed by a short id. Nothing is merged for you.

To review the work, open the Changes panel for the thread. It lists every changed file with its diff. From there you can Create PR or Create draft PR, and once a pull request exists, View PR takes you to it on GitHub.

Connected tools

Remote MCP servers you connect in Settings › Connections are available to cloud sessions, so a run can read from the systems you already use.

Local MCP servers, the ones configured on your computer in ~/.perch/mcp.json, are not. The cloud workspace cannot reach your machine. A task that needs local files, local apps, or a local server should run on your computer instead.

When a step needs your OK, the thread asks and waits, the same as it does on Desktop. Answer from whichever screen you have open.

Slack

You can hand Perch a task without opening it at all.

1. In Perch Terminal on the web, go to Settings › Connections and select Add to Slack.
2. Link your Slack account to your Perch account when Perch asks you to.
3. Send Perch a direct message, or mention it in a channel.

Each message runs as a cloud session and the answer comes back in the same Slack thread. A Slack thread maps to one Perch thread, which also shows up in your thread list, so you can pick it up in Perch Terminal later.

If a step needs your approval, Slack tells you to open Perch to answer it. Approving from inside Slack is not supported yet.

Usage and limits

• Model usage counts toward your plan's normal limits, the same as any other chat.
• Cloud workspace time is capped at 30 hours per billing period. Settings › Usage › Cloud agents shows how much you have used. Once you reach the cap, new cloud runs are refused until the next period starts.
• Messages that run on your own computer never count toward workspace time.

Security

Each session runs in its own isolated sandbox, separate from every other user's. Only short-lived access tokens for your connections go into the workspace; the long-lived tokens stay on Perch's servers.

Troubleshooting

I do not see Cloud in the menu. Cloud agents are not on for your account yet. They are rolling out to Pro accounts in stages.

My repository is not in the list. Perch lists the repositories your GitHub account can push to. For an organization's repositories, the organization may need to allow Perch's GitHub access first. Select Reconnect GitHub to sign in again.

Perch will not start a cloud run and says I am out of workspace time. You have used this period's 30 hours. Messages that run on your own computer still work, and the allowance resets with your billing period.