Sign InGet Started

Cloud Agents

Configure one Cloud Agent, point it at a repo, paste your .env, hit Save. A minute later it shows "Active" with a fresh snapshot — and every brief on that repo can deliver in parallel without touching anyone's laptop.

Overview

A Cloud Agent is a reusable cloud sandbox — one per repo (or set of repos) — that Hamster boots to deliver briefs. You configure it once from a single page in settings, and from then on any teammate can deliver a brief into that Agent without spinning anything up locally.

Before Cloud Agents, every engineer wired up Hamster on their own laptop: cloning, env vars, build commands, then babysitting a sandbox terminal to "Save & Stop" before a snapshot was usable. Cloud Agents replaces that with one modal. Save auto-builds, auto-snapshots, and lands on Active. Reset rebuilds in place. Multiple Agents per team mean you can run parallel deliveries against different repos.

The list page shows every Agent for the workspace, its status, and which repos are attached. Status updates in real time as the sandbox builds, so you see exactly when an Agent flips to Active and is ready to take work.

How It Works

  1. Create a Cloud Agent — Open Settings > Cloud Agents and click New Cloud Agent. The configuration modal opens.
  2. Name and attach repos — Give the Agent a name and add one or more GitHub repositories. The repo chips show what the Agent has access to.
  3. Paste your .env — Drop a .env file into the env vars section. Hamster parses it, dedupes keys, strips quotes and comments, and stages the variables. You can paste a full monorepo .env (up to 500 keys) in one shot.
  4. Set commands per repo — Configure the build, install, test, and run commands for each attached repo. Textareas grow with the content.
  5. Save — Hamster persists the config, kicks off a sandbox build, and snapshots the result automatically. The Agent's status moves through Pending → In progress → Active.
  6. Deliver against it — Once Active, any brief on a connected repo can deliver in parallel. Each delivery boots a fresh sandbox from the snapshot in about 30 seconds instead of building from scratch.

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 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. A common pattern:

  • One Agent per repo for single-repo teams.
  • One Agent per app inside a monorepo, each with the right command set baked in.
  • A separate Agent 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.

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.

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.

Related