Cloud agent setup

Before a cloud agent can work on your code, you connect a repository and define the environment it runs in — the install steps, secrets, and network access it needs to build and test like your team does locally.

Setup is usually once per repository. After that, each new run reuses the same configuration unless you change it.

Think of it like giving the agent a cloud machine with your repo checked out: dependencies installed, tests runnable, and credentials available — without pasting secrets into chat.

What you are setting up

Your org admin may configure some of this centrally. Members pick the repo and branch when starting a run in the Agents workspace.

Before you start

If repositories do not appear in the picker, ask your admin to confirm the integration is installed and the repo is allowed.

Connect a repository

1. Install the integration

   Your organization connects GitHub (or another supported provider) and grants access to the repositories cloud agents may use.

2. Allow the repositories you need

   Only repos your org allows show up in the Agents workspace. Admins can add more later from the integration settings without reinstalling the app.

3. Pick repo and branch

   In the Agents workspace, select the repository and starting branch. The agent creates a working branch from there unless your task says otherwise.

Configure the environment

Cloud agents run in an isolated environment — not on your laptop. Tell X4RGE what the agent needs so the first command in your task does not fail on a missing dependency.

Install and build steps

Add the same commands your team runs after cloning — for example installing packages and building the app. Match what you use in CI when possible so cloud runs behave predictably.

Typical steps:

• Install dependencies (npm ci, pnpm install, pip install, and similar)
• Generate code or build if your project requires it before tests run
• Run safe database or schema steps only if your workflow supports ephemeral environments

Secrets and configuration

Provide secrets through your org's environment or secret settings — never paste API keys, tokens, or passwords into agent prompts.

Secrets are injected at runtime. They are not written to git, chat, or run logs.

Match your stack

Choose runtime settings that mirror your project — Node, Python, Go, or a custom image for polyglot monorepos. Pin versions to match CI so "works in cloud" matches "works in pipeline."

Admins configure network and image details in Security & network.

In practice

If setup is wrong, runs fail early with clear logs — fix configuration once, then reuse it.

Verify the setup

1. Run a small test task

   Start a short cloud run — for example, print the runtime version and run your test suite for one package. Confirm install steps succeed.

2. Check network access

   If the task needs external hosts (package registry, private API), confirm your org's egress rules allow them. Failed installs often mean a blocked registry.

3. Open a test pull request

   Ask the agent for a trivial change and a PR. Confirm permissions and branch flow work end to end before larger tasks.

For admins

When onboarding a new repository for cloud agents:

1. GitHub (or provider) app installed with repository access granted
2. Repository visible in the Agents workspace picker
3. Startup commands tested with a smoke run
4. Secrets configured — no values in prompts
5. Egress allowlist covers registries and required APIs
6. Usage and budget policy allow cloud runs for the team