Project Spec: Cloud Agents
1. Introduction
Cloud agents enable running Kilo Code CLI agents in the cloud, offloading computation from the user's local machine and providing easy isolation.
For a minimum-viable product, upload a snapshot of the local repo's main branch HEAD to the cloud, execute the agent task there, and automatically download results as a patch/commit to apply locally on a new branch.
No GitHub integration or token is required in v1, simplifying auth and setup.
Status during agent execution is streamed to the developer’s local Kilo Code CLI, displaying status within the same Terminal UI used to display the status of Parallel Agents spec.
2. Requirements
User Initiation
- From CLI:
kilocode --cloud "Task description"
- Assumes current dir is the repo root, on main branch (error if not)
- Stamp a local tag we can use later to apply a patch
- Creates a zip of the current HEAD:
git archive --format=zip HEAD > repo.zip
- Uploads zip to cloud backend (e.g., via HTTP POST to kilocode.com/api/upload), gets session ID in response
- Displays status within Kilo Code’s CLI
Cloud Execution
Backend
- Receives zip and task description
- Spins up ephemeral sandbox
- Unzips to temp dir, runs agent:
kilocode "Task description"
- Status updates are available to the end-user’s CLI
- If succeeds: Generates patch
git diff > changes.patch
, or zip the modified dir. - Stores encrypted result (patch/zip) keyed by session ID
- Handle failures: Store error message/log
Result Retrieval
- Kilo Code CLI polls cloud-agent status updates and displays in CLI
- When done, if cloud succeeded, downloads patch
- Applies locally: Creates new branch
git checkout -b kilo-task-<id>
, applies patchgit apply changes.patch
, commitsgit commit -am "<AI-generated message>"
.
Non-functional
- Security
- Ephemeral sandboxes without network access
- Delete data after download/expiry
- Use HTTPS for transfers
- Basic anti-abuse limits
- Agent Interaction: Autonomous run; fail on input needs, suggest local retry
Open Questions
- How can we exclude secrets while still getting `.gitignore`d dependencies such as `node_modules`?
3. Non-goals
- GitHub integration (PRs, tokens) – deferred
- Support for non-main branches or dirty repos
- Multi-repo or persistent cloud storage
- Support for custom runtime environments
4. Prior Art
- Google's Jules: Remote execution inspiration, but simpler here without auth
- Roomote: https://www.youtube.com/shorts/Mh3D_8837Bo – For remote envs; consider hiring contributor
- Roo Cloud: Leverage existing extension functionality (minute 52: https://www.linkedin.com/events/7378875994083897344/)
- Sandboxes: Vercel https://vercel.com/docs/vercel-sandbox or Cloudflare https://sandbox.cloudflare.com/
- Similar: Replit-like snapshots, but minimal transfer focus