Core concepts

A few concepts show up across the entire platform. Understanding them makes everything else easier to navigate — from your first local agent run to enterprise contract management in the Console.

Organization

An organization is the top-level container for your company or team. It owns members, projects, billing, the model catalog, and policy. Almost everything you configure lives at the organization level so it applies consistently to everyone.

When you sign in, you land in one organization (your workspace). Multi-org users switch between orgs from the app shell; each org has its own members, projects, usage, and settings.

Members and roles

People are members of an organization. Roles determine what they can do:

super_admin and admin are the roles that unlock the organization's admin areas; member is the standard role. Platform operators (your 4RGE vendor or internal platform team) manage cross-org concerns separately from the Console.

Project-level roles can further restrict who sees which repositories — see Project members.

Projects

A project groups related work: a repository, its tasks, views, and the members who can access it. Projects give the agent scope and give your team a place to track progress. See Projects.

Typical project contents:

• Linked repository — the source of truth the agent and cloud runs use
• Tasks — units of work with status, assignees, and links to agent runs
• Views — filtered boards or lists for leads tracking sprint progress
• Members — who can start runs, approve work, or only view status

Projects do not replace Git — they organize how your team uses 4RGE on top of Git.

Agents

An agent is the AI that reads your code, plans changes, runs tools, and edits files. 4RGE has two surfaces for agents:

• Desktop agent — runs locally in the app or CLI against your working tree.
• Cloud agents — run remotely so long tasks continue without your machine. See Cloud agents.

Both surfaces use the same agent loop: understand context → act via tools → verify with tests or checks → present a diff. Desktop runs block on your approvals; cloud runs can notify you on mobile or via Slack when input is needed.

Agent run sources

Every cloud run stores a source field in x4rge_agent_runs: cloud_ui (started from the Agents workspace), github_app (webhook-driven), bitbucket_app, or api (CLI or automation). The source appears in run metadata and audit events, which helps Sentinel distinguish manual runs from automation-triggered work. Local desktop and CLI runs use the same tool broker but do not create cloud run rows unless you explicitly hand off to a cloud-backed target.

Models

Agents are powered by models from one or more providers. Your organization defines a model catalog — which providers and models are available, and the defaults per surface (desktop, CLI, cloud). Admins manage this in Model control.

Usage from every model call rolls up to Usage & billing under your org.

Tool broker

Agents do not get raw, unrestricted access to your machine or network. The tool broker mediates every tool call through controlled categories:

The broker enforces organization policy — which categories are enabled, what cloud egress is allowed, and what plugins expose. Because all tool use flows through one layer, desktop and cloud runs produce auditable, consistent behavior.

Data flow (how a run moves through the platform)

You do not need to memorize every service, but this end-to-end picture helps when debugging access, usage, or integration issues.

1. Identity and org context. You sign in through your organization's identity provider. The app or CLI attaches your user, role, and organization to every request.

2. Project and repository scope. You open a folder locally or select a project/repository for a cloud run. That choice defines which files, secrets policies, and integrations apply.

3. Prompt and model routing. Your message goes to the agent orchestration layer, which selects a model from the org catalog (unless you picked one explicitly). Model control and Console capacity checks happen here.

4. Tool broker execution. The agent plans steps and requests tools — read a file, run npm test, call an MCP server. The broker enforces approvals, .gitignore, network policy for cloud runs, and plugin allowlists.

5. Output and review. Results return as chat, logs, and a diff. Locally you accept or discard changes. In the cloud the agent may open a GitHub pull request via integrations. Usage meters record token spend.

6. Dashboard and operator visibility. Runs and spend appear on the org dashboard. Platform operators see aggregate capacity and contracts in the Console — a separate plane from org admin work.

You (desktop / CLI / mobile)
    → sign-in & org policy
    → project / repo scope
    → agent + model catalog
    → tool broker (repo · terminal · browser · MCP · workspace)
    → diff / PR / task update
    → usage dashboard (org) · contracts (console)

Integrations overview

Integrations connect 4RGE to the tools your team already uses. They are org-level connections configured by admins; members consume them through agent and cloud runs.

GitHub is usually required for cloud agent setup — the agent clones, branches, and opens PRs through the installed GitHub app. Slack and Linear are optional but common for teams that want 4RGE in their existing workflow tools.

Plugins from the marketplace are a related but distinct concept: they add agent tools (often MCP servers) rather than org-wide OAuth apps. Admins may allow both integrations and plugins, or curate a subset.

Usage, budgets, and contracts

Every agent run consumes usage (tokens / spend). Two layers govern it:

• Budget policies are set by your org admins to cap internal spend. See Usage & billing.
• Contracts and capacity are set by platform operators in the Console and define what your org is entitled to.

When a budget threshold is approached, admins may receive warnings or members may see softer limits in the model picker. Hard stops depend on how your org configured policies.

Putting it together