Concepts in five minutes

SupaCloud is a self-hosted orchestrator for AI coding agents: you connect your repositories, and it launches agents against them in containers on machines you control. What makes it more than a wrapper around a coding CLI is that every part of that is a first-class object you can inspect — the work, each attempt at the work, who was allowed to do it, how far it could go before asking you, and what it cost.

The other pages in this section are precise about each of those objects. This one is the vocabulary they assume: about ten words, one short paragraph each, every one ending in the page that goes deep.

Organization and workspace

There are two nested tenants. An organization is the top one — it owns billing, seats, single sign-on and invitations, and every user belongs to exactly one (a personal one is created for you at signup). Underneath sits the workspace, the container everything else lives in: projects, tasks, runs, workflows, schedules, secrets and connections. Membership is per user, and your active workspace tells the server which organization you are acting in — there is no organization switcher, and most people work in one workspace and rarely think about the layer above it. Workspaces and Organizations has the full hierarchy and how entitlements resolve through it.

Project

A project is one repository’s worth of work inside a workspace. It binds the git repository an agent clones and, optionally, an issue source — the Git forge’s own issues, Linear or Notion — so a project can be repository-only, tracker-only, or both, and it carries the credentials, automation settings and merge policy that apply there. Every agent run happens against a project, which is why a task cannot be moved between them after the fact.

Task and run

This is the distinction worth learning first, because much of the UI is shaped by it. A task is the durable definition of a piece of agentic work — project, prompt, agent, profile, model, linked issue. A run is one execution: a container starting, working and stopping, with its own status, cost and append-only event log. Restarting a task therefore overwrites nothing; it creates a new run with the next attempt number and a clean event log, which is why a task’s history survives as many attempts as it takes. Runs and tasks covers the run kinds, the restart behaviour and the lenses you can look at a run through.

Agent and agent profile

An agent is the coding process SupaCloud spawns for a run. Several are supported — Claude Code, Codex, opencode and others — and from your side they behave alike: they work in the container and reach back into SupaCloud through tools. An agent profile is the saved who: which model, which tool tiers the agent may use, which pre- and post-flight checks it must pass, and which execution mode it runs in. Pinning a profile to a task, an automation or a whole workspace says “work like this” once instead of on every launch — and a task with no profile deliberately gets a narrow read-only surface, not a generous default.

Workflow

Not all work fits one prompt. A workflow is a declarative graph of nodes — agent steps, code, database queries, connectors, branching gates, human checkpoints — that you draw in a visual builder and that executes as a run. It is the same run model, so each node becomes a child run of the workflow run and you can drill from the whole graph into one agent’s event log. Workflows are where multi-step work with conditions, retries and a human in the middle belongs. Build your first workflow walks one from empty canvas to a finished run.

Automations

An automation turns an event into work without you launching anything. Each project has one Automation section, and its autodev mode decides what happens to incoming issues: Off imports them but dispatches nothing, Simple works each new issue straight through to a pull request in arrival order, and Backlog collects, classifies and prioritises them first. A separate pull-request-review lane runs on pull-request webhooks independently of that mode. Issues are always imported whatever the mode — the mode governs only whether they are dispatched. Automations explains the modes, the classifier and the supervision controls they share.

Autonomy and approvals

Autonomy is one number from 0 to 100 — set per workspace, project or agent profile — that decides how far an agent may go alone: whether work dispatches unattended at all, how readily the agent stops to ask you something, and how far a change may travel (open a pull request and wait, merge once CI is green, or merge outright). It snaps to five named stops from Manual to Unleashed, and two hard ceilings — your plan, and a cautious cap while a workspace is still onboarding — can only ever lower it. Where an agent does stop you get an approval: one pending decision — a dangerous tool call, an open question, a screenshot to sign off — that blocks that run until you answer. A run’s policy is frozen at launch, so moving the slider never changes work already in flight. Autonomy and the delivery engine has the stops and the resolution order; Approve or reject agent actions shows what answering looks like.

Tool tiers

Autonomy decides how far an agent goes; tool tiers decide what it may touch at all. Everything an agent does to SupaCloud passes through a tool surface split into tiers — an always-on baseline, read-only situational awareness, operational triggers, scaffolding, and deployment — and an agent profile’s allowlist names the tiers that session receives. The dangerous end is fail-closed: without an explicit grant an agent gets reads and nothing more, and deploying an app or applying a migration also needs an owner or admin actor plus a signed two-step confirmation that no autonomy setting can wave away. Entitlements and the MCP tool tiers lists the tiers, their rate limits and how edition and plan compose with them.

Runners

A runner is the machine that physically executes a run’s container. By default that machine is the SupaCloud server itself, which is all most installations ever need — a single host happily runs many agents at once. Switch the fleet on and the same work is claimed instead by separate worker machines that connect outward to the server and ask for jobs, so a runner needs no inbound ports and keeps no copy of your database. Either way the events, costs and logs land in the same place, so a run looks identical wherever it executed. The runner fleet explains when that trade is worth making.

Marketplace

Not everything has to be built. The marketplace is a catalog of installable pieces: workflows, scripts, sandboxed connectors that add a new node type to the builder, apps, and bundles that carry several of those together so one install brings a whole product instead of two listings and a README. Items may be free or paid, and those that passed the automated review gate carry a Verified badge. Installing binds an item to your own credentials — a connector’s network access reaches only the connections you map at install time. Install a marketplace connector runs through one install end to end.

The surfaces

The web UI is not the only way in. The same control vocabulary — launch, follow, intervene, cancel, approve — is available in the web terminal at /cli, from a linked Telegram chat, and from Discord, and a command word means the same thing on all three because they read one command catalog. That matters in practice: you launch a run at your desk, watch it stream in Telegram from a train, and answer its approval from your phone. Inside the web UI, related surfaces fold into a few hub routes rather than a long sidebar — Navigation and hubs explains that shape, and Web terminal commands is the full command set.