Cloud Agents

Configure one Cloud Agent, point it at a repo, paste your .env, hit Save. A minute later it shows "Active" — and from then on any teammate can deliver a brief or task from the cloud, in parallel, without anyone's laptop in the loop.

Overview

A Cloud Agent is a configured cloud sandbox plus the AI agent that runs inside it. The sandbox knows your repo URL, your env vars, and your build and test commands. The AI agent knows the brief, the relevant blueprints, and the methods. When a teammate clicks Deliver on a brief — or /ship from Slack, or hands a task to the agent from the task page — the Cloud Agent boots, the AI executes the work, and a pull request lands in your repository.

Cloud Agents complement the IDE flow rather than replacing it. Most engineers ship from their IDE using the Hamster CLI and MCP server — they want control. Cloud Agents are the path for deliveries that don't need an engineer at the keyboard: a PM clicking Deliver on a brief, Routines running scheduled work, parallel deliveries across the team that shouldn't queue on engineer time.

How it works

Configure once. Open Settings > Cloud Agents and create a new Cloud Agent. Name it, attach one or more GitHub repositories, paste your .env, set the install/build/test/run commands per repo. Save.
Hamster builds and snapshots automatically. Status moves through Pending → In progress → Active. Once Active, the sandbox snapshot is ready and any brief on a connected repo can deliver into this Agent.
Deliver from a brief or task. Click Deliver on a brief, or hand a task to the Agent from the task detail page. The Agent boots a fresh sandbox from the snapshot in about 30 seconds, the AI executes, and a PR is opened in your repo.
Watch the delivery thread. The agent's narrative streams live in the brief (or task) thread — every tool call, every flow step, the PR push. You can interrupt it at any time by typing into the thread.

Status

Each Cloud Agent shows a status pill that mirrors the sandbox lifecycle:

Pending — Configuration saved, sandbox build hasn't started yet.
In progress — Building, restarting, or stopping.
Active — Sandbox snapshot is ready. Briefs and tasks can deliver into this Agent.
Needs action — The build hit an error. Open the Agent to see what happened and try again.

The list updates live, so you can save a config and watch the pill change without refreshing.

Env vars

Env vars are encrypted at rest and never exposed in the UI after they're saved. You can paste:

A full .env blob — comments, blank lines, and export prefixes are tolerated.
Individual key/value pairs — single and double quotes are stripped.
Multiple paste operations — last-write-wins per key, so re-pasting an updated .env overrides the prior value cleanly.

Vars are scoped to the Cloud Agent and made available to the sandbox at delivery time.

Multiple Cloud Agents

You can run as many Cloud Agents as your team needs. Common patterns:

One Agent per repo for single-repo teams.
One Agent per app inside a monorepo, each with the right command set baked in.
Separate Agents for staging vs. production deploys, with different env vars on each.

Two briefs targeting different Agents deliver in parallel without contention. Two briefs targeting the same Agent each get their own sandbox, also in parallel, booted from the shared snapshot.

What the agent receives

When a delivery launches, the AI agent inside the Cloud Agent receives:

The brief — title, description, scope, acceptance criteria, attached context (Figma frames, customer-call clips, screenshots, URLs).
Relevant Blueprints from your team's Context Graph — what the product is today, what the relevant systems are.
Methods from your team's Methods Library — how your team works, testing patterns, deploy procedures.
The repository, branch, and any additional instructions you provide at launch time.

The agent uses all of this to understand not just what to build, but why and how — which leads to more contextually appropriate implementation than a generic AI coding tool would produce in isolation.

Run states

Each delivery moves through a set of states Hamster tracks and displays:

Pending — The run has been created and the agent is starting up.
Running — The agent is actively working in the sandbox.
Completed — The agent finished and opened a pull request.
Failed — The agent encountered an error. The run record includes details.
Cancelled — The run was cancelled before completion.

Only one delivery can be active for a given brief at a time. If you try to launch a second run while one is in progress, you'll wait for it to finish or cancel it first.

Reset

If a Cloud Agent stops booting cleanly — bad commit, broken dependency, stale snapshot — open the Agent's overflow menu and click Reset. Hamster clears the live sandbox handles, flips the Agent back to Pending, and re-runs the build. When it lands on Active again, it has a fresh snapshot.

Reset is the right move when:

A delivery has failed repeatedly and you suspect the snapshot is stale.
You've changed env vars or commands and want a clean rebuild.
You've upgraded the underlying repo's toolchain and want the Agent to pick it up.

Permissions

Workspace Admins and Creators can configure Cloud Agents — create, edit, reset, and delete. Other roles can deliver briefs into any Active Agent but cannot change the configuration. For sensitive environments (e.g. production deploys), use the Admin role to gate configuration changes.

Cloud Agents vs the IDE flow

Cloud Agents and the IDE flow (Hamster CLI + MCP server) are two paths to the same destination — a PR in your repo from a brief. Use whichever fits the situation:

IDE flow — engineers stay in Claude Code, Cursor, or Codex. They keep control. Best for engineer-driven work where someone wants to be in the loop on the agent's choices in real time.
Cloud Agents — deliver without an engineer at the keyboard. Best for PM-driven deliveries, Routines, parallel work across the team, or anything kicked off from Slack via slash commands.

Most teams use both. The CLI/MCP path for individual engineers; Cloud Agents for everything else.

Tips

Keep your .env source of truth somewhere stable (1Password, a secrets manager). Re-paste into the Cloud Agent any time the source changes; the parser handles re-paste cleanly.
Use a descriptive Agent name that includes the repo or app — "API", "Web app", "Marketing site" — so teammates know which Agent to pick when delivering.
If you have multiple repos that share a build pipeline, attach them all to one Agent. Briefs that touch any of them can use the same snapshot.
Cloud Agents and the Slack bot work together: each Agent gets its own slash command flow, so a teammate can deliver a brief into a specific Agent directly from a Slack channel.
Write clear, specific briefs and tasks before launching. The more precisely the acceptance criteria are written, the better the agent's output will be.
Check the pull request carefully before merging. Cloud Agents are capable, but code review remains important — especially for changes with security implications or complex integration points.
If a run fails, check the run details for an error description. Common causes include repository access issues or ambiguous instructions the agent couldn't resolve.

Hamster CLI — the IDE/terminal path, for engineers who want control.
MCP Server — exposes Hamster context to Claude Code, Cursor, and Codex.
Briefs — the artefact a delivery ships.
Routines — automated, event-driven deliveries.
GitHub — required for delivery PRs.