Cloud agent setup

Before a cloud agent can work on your code, connect a repository and define the environment it runs in. Setup is a one-time per-repository configuration; subsequent runs reuse the same environment unless you change it.

Prerequisites

Connect a repository

1. Install the integration

   Connect your Git provider (for example GitHub) and grant access to the repositories cloud agents may use. The GitHub app must be installed on the organization or account that owns the target repositories.

2. Select repositories

   Choose which repositories are available to cloud agents in your organization. Only allowlisted repositories appear in the Agents workspace picker. You can expand access later from GitHub's app settings without reinstalling.

3. Sync repository metadata

   After connecting, 4RGE syncs branches and installation metadata. If repos don't appear, confirm the GitHub app has access to them and check Troubleshooting for local sync requirements.

4. Pick a default branch

   In the Agents workspace, select the repository and branch the agent should start from. Cloud agents create a working branch from this base unless you specify otherwise in the task.

Configure the environment

Cloud agents run in an isolated environment. Specify what they need so the first command in your task doesn't fail on a missing dependency.

Setup commands

Run these once when the environment is created (before the agent starts your task):

# Node.js monorepo example
npm ci
npm run build --workspace=apps/web
 
# Python example
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment variables and secrets

Provide secrets securely — never paste them into prompts:

Secrets are injected at runtime into the cloud sandbox. They are not written to git, prompts, or run logs.

Base image and runtime

Choose a base image that matches your project's language and tooling:

Environment lifecycle states

Each cloud run tracks an environment status on the run record: provisioning, active, idle, suspended, deleted, or failed. Fresh environments start in provisioning while setup commands run; they move to active when the agent can execute tools. Idle environments may suspend after inactivity and are eventually deleted per org retention settings — ephemeral by design. A failed environment usually means setup commands or clone steps broke; check run logs before retrying with the same repository configuration.

Verify the setup

1. Run a smoke-test task

   Start a short cloud run: "Print the Node version and run npm test for the root package." Confirm setup commands succeed and tests can execute.

2. Check network access

   If the task needs external hosts (npm registry, private API), verify those domains are on your egress allowlist. A failed npm ci often indicates a blocked registry.

3. Open a test pull request

   Ask the agent to make a trivial change (update a comment) and open a PR. Confirm GitHub permissions and branch naming work end to end.

Operator checklist

Platform and org admins use this checklist when onboarding a new repository to cloud agents:

1. GitHub app installed with repository access granted.
2. Repository appears in the Agents workspace picker.
3. Setup commands documented and tested in a smoke run.
4. Required secrets configured (no values in prompts).
5. Egress allowlist includes package registries and any private APIs.
6. Budget policy allows cloud agent usage for the team.