Cloud agents overview

Cloud agents run remotely instead of on your machine. Start a task, close your laptop, and the agent keeps working — building, testing, and opening changes for review when it finishes.

Unlike local runs that depend on your IDE session, cloud agents execute in an isolated environment with the repositories, secrets, and network access your organization allows. Results arrive as diffs, pull requests, or status updates you review on your schedule.

When to use cloud agents

Scenario	Why cloud
Large refactors	Runs can take hours; no need to keep your laptop open
Parallel work	Kick off several runs while you focus locally
CI-adjacent fixes	React to failing checks without context-switching
Scheduled maintenance	Automations triage issues, scan for bugs, or update docs overnight
Team handoffs	A run started by one person can be reviewed by anyone with access

Common use cases:

Long-running tasks (large refactors, broad test fixes).
Work you want to run in parallel with your local development.
Automated workflows triggered by events (see Automations).
Tasks that need a consistent Linux environment regardless of your local OS.

How it works

Start a run
Kick off a cloud agent from the Agents workspace with a task description, target repository, and branch. You can also start a run from an automation or a connected integration such as GitHub.
It runs remotely
The agent executes in an isolated cloud environment. It clones the repository, runs your setup commands, and works within the network and permissions your org allows. Usage is reserved against your budget and contract before the run starts.
Monitor progress
Watch messages, terminal output, and git changes stream in real time. Use Sentinel for org-wide visibility when multiple runs are active.
Review the result
When it finishes, review the diff or pull request just like local work. Accept changes, request follow-ups, or discard the run.

Run lifecycle and billing

Cloud runs are created through the agents API (POST /api/agent-runs on agents-api.4rged.ai). Before execution starts, 4RGE calls reserveAgentRunUsage — if the org is over contract or budget limits, the API returns 402 with a policy message. On success, the run is enqueued to the worker job queue and progresses through worker processing.

Stage	What happens
Preflight	Auth, repo access, and usage reservation
Queued	Job waiting for an available worker
Running	Agent executes setup commands and task in the sandbox
Complete	Diff, commits, or PR available for review

Run status values

The dashboard overview tracks runs from x4rge_agent_runs. Status values include queued, starting, running, and waiting for in-progress work, plus terminal states such as completed and failed. Use Sentinel or the Agents workspace run stream (/api/agent-runs/[runId]/stream) to monitor active runs across your org.

Cloud vs local agents

	Local agent	Cloud agent
Where it runs	Your machine / IDE	Isolated cloud sandbox
Session required	Yes — IDE must stay open	No — runs after you close the laptop
Network	Your machine's network	Org-configured egress allowlist
Best for	Interactive iteration	Long jobs, automation, parallel work

Start small

Run a short, well-scoped task first (for example, "add a unit test for parseDate") before delegating a multi-hour refactor. Confirm setup commands and repository access work as expected.

What you need before starting

Connect a repository
Install the GitHub integration and grant access to the repositories cloud agents should use. See Setup for environment configuration.
Confirm budget headroom
Cloud runs consume against your organization's allowance. Check Usage if runs are denied with a policy error.
Review network policy
If your project needs package installs or external API calls, confirm the required domains are on your egress allowlist. See Security & network.