Skip to main content

Installation

Most people start with the desktop app — install it, sign in, open a repo, and run your first agent. This page walks you through that path in plain language. CLI, cloud, and mobile are optional add-ons you can set up later.

You do not need every surface on day one. Get the desktop app working, then explore the rest when your workflow needs them.

What this page is for

You want to…This page helps you…
Install the desktop appDownload, install, sign in, open a project
Check you have what you needAccount, OS, and network basics
Pick the right surfaceDesktop vs CLI vs cloud vs mobile
Confirm install workedA short checklist before Quickstart
Fix install issuesKnow when to jump to Troubleshooting
Already invited?

You need an organization invitation before sign-in works. Ask an admin from Members if you do not have one yet.

Who this page is for

You are…Focus on
New developerInstall the desktop app → After install
Terminal-first engineerDesktop first, then CLI installation
Team lead / adminShare this page with new hires; use hidden ops notes if IT needs allowlists
Mobile approver onlyOther ways to use X4RGE → mobile row

Before you install

You need…Why
A X4RGE accountSign in through your org's identity provider after install
An org invitationWithout it, sign-in will fail — ask an admin
A supported OSmacOS 13+, Windows 10/11, or a recent Linux distro
Internet accessFor sign-in, updates, and agent runs
A Git repo (recommended)Open the project root so the agent sees the full codebase

Rough hardware: 8 GB RAM minimum (16 GB for large monorepos), about 2 GB free disk, and a display at least 1280×800. Git on your PATH is strongly recommended.

Corporate laptop?

Locked-down machines may need IT to allow the installer and X4RGE domains. Point them to Cloud agents · Security & network if a proxy or firewall blocks sign-in.

Install the desktop app

Same shape on every platform: download → install → sign in → open a folder. Most people are ready in under five minutes.

  1. Download

    Get the installer for your platform from your organization's X4RGE download page (or the link your admin shared). Pick macOS, Windows, or Linux — see Choose your platform below if you are unsure.

  2. Install

    Run the installer for your OS. macOS: drag the app to Applications. Windows: run the .exe and follow the prompts. Linux: use the .deb, .rpm, or package your org provides.

  3. Sign in

    Launch X4RGE and sign in with your work account. You should land in your organization's workspace. First launch may download extra components — that is normal.

  4. Open a repository

    Use File → Open Folder and choose your Git repository root (not a nested subfolder). The agent scopes work to this directory.

Optional: CLI from the app

Many teams also install the CLI for terminal and CI workflows. You can add it from the in-app setup flow or install it separately — desktop and CLI share the same account and model settings.

Choose your platform

PlatformWhat to do
macOSOpen the .dmg, drag X4RGE to Applications, launch from Applications. Universal builds run on Apple Silicon and Intel.
WindowsRun the 64-bit .exe installer. If you live in WSL, open repos from a path your tools can reach, or use the CLI inside WSL.
LinuxInstall the .deb or .rpm your org ships, or follow their portable package instructions. Grant folder access when the app asks.

If install or first launch is slow, antivirus or corporate policy may be scanning the app — see Troubleshooting.

Other ways to use X4RGE

You do not install a full IDE for every surface. Here is how the rest fits:

SurfaceBest forInstall?
Desktop appDay-to-day coding with the agentYes — main path on this page
CLITerminal, scripts, headless CISeparate install — CLI installation
Cloud agentsLong tasks that keep running after you close your laptopNo local IDE — start from app, CLI, or automations; needs GitHub for most PR workflows
Mobile companionNotifications and approvals on the goApp store or MDM link from your org — optional
Cloud needs a connected repo

Cloud agents run in X4RGE-managed environments. Set up repository access first — see Cloud agents · Setup.

Desktop + CLI together is common: IDE for interactive work, CLI for quick fixes and pipelines. Both respect Model control defaults.

After install

Confirm the basics before your first real task:

  1. Sign-in works — you see your organization name in the app shell.
  2. Repo opens — the agent panel loads for your project folder.
  3. A model is available — check the model picker; if empty, ask an admin about Model control.
  4. A tiny task runs — try "Summarize the README" and approve one tool step.

When all four pass, continue to Quickstart for your first meaningful change.

The desktop app updates itself in the background — restart when prompted. The CLI may update separately; see CLI installation for your org's recommended version.

Where to go next

Your goalNext doc
First agent taskQuickstart
Learn the vocabularyCore concepts
Install the CLICLI installation
Background / PR workflowsCloud agents
Something failedTroubleshooting

Questions about installation?

QuestionAnswer
Do I need desktop and CLI?No — desktop alone is enough to start. Add CLI when you want terminal or CI.
Do I need cloud installed locally?No — cloud runs remotely; you start them from desktop, CLI, or automations.
Is mobile required?No — useful for approvals and cloud notifications, not for writing code.
What if sign-in loops?Check your invitation and corporate proxy — Troubleshooting.
Who picks my models?Admins set the catalog — Model control.
Can I use X4RGE without Git?You can open a folder, but Git repos work best for diffs and cloud PRs.
Quickstart

Sign in, open a repo, and complete your first agent task.

Core concepts

Org, project, agent, and model — the map in plain language.

CLI installation

Terminal install, login, and first run.

Cloud agents

Long-running work without keeping your laptop open.

Troubleshooting

Sign-in, network, and install issues.