Sign InGet Started

Cloud Agents

Configure one Cloud Agent, point it at a repo, paste your .env, and save. Once it shows "Active", teammates with delivery permission can ship 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, launches from a Task, triggers a Routine, or uses /ship from Slack, 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 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, or Slack slash flows that should not queue on engineer time.

How it works

Setting up a Cloud Agent uses a guided flow:

  1. Repository detection — Connect your GitHub repository and Hamster analyzes its languages, frameworks, build system, and package manager.

  2. Setup plan — Hamster proposes Install, Build, Test, and Run commands plus relevant environment configuration. Review and refine the plan before saving.

  3. Install validation — Hamster prepares the sandbox and automatically executes the Install phase. An install failure surfaces as an actionable setup error. Build, Test, and Run remain available to the coding agent during delivery rather than running as setup gates.

  4. Snapshot creation — After installation succeeds, Hamster creates a reusable snapshot. Deliveries boot from that prepared environment instead of repeating the initial setup.

After setup completes, the Cloud Agent shows Active and is ready to deliver. You can configure multiple repositories and multiple Cloud Agents for different parts of your codebase.

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.

Commit Attribution

When a Cloud Agent opens a pull request, it creates commits with the following properties:

  • Author attribution — Commits are authored by hamster[bot], a GitHub bot account that represents the Cloud Agent's work.
  • Human attribution — The PR description includes the name of the person who triggered the delivery, so reviewers know who initiated the work.

Commit verification status is environment-dependent and best-effort. By default, commits are unsigned. When signature verification is available, Hamster will attempt to sign commits; if that fails, commits fall back to unsigned. Commit signature verification is not configurable per workspace.

Permissions

Configuring Cloud Agents requires the environments.manage permission, while delivering a Brief requires documents.manage. The seeded Owner, Admin, and Creator roles can deliver; Reviewers cannot. For sensitive environments, grant these permissions only to the roles that should configure or launch work.

Plan

Cloud Agents are available on Team and Enterprise plans. If your workspace is on the free plan, clicking Deliver on a Brief or opening the Cloud Agents settings will show an option to upgrade.

The Team plan now starts at a single seat — there's no creator minimum. See the pricing page for current rates.

Cloud Agents vs the IDE flow

Cloud Agents and the IDE flow (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.

Related