How Mogplex Fits Together
Understand the Mogplex object model from account state and routing to missions, tasks, Worktrees, Sandbox compute, runs, and observability.
Mogplex is easier to debug once the platform objects have clear ownership.
Most product questions reduce to this chain:
account -> GitHub installation -> repo -> agent -> route -> run -> observability
|
+-> mission -> task -> Worktree
|
v
Sandbox computeA run can use Sandbox compute without a Worktree. A planned coding task uses a Worktree when it needs an isolated checkout. The Worktree binds explicitly to one Sandbox, branch, task, and checkout path.
Each object answers a different question.
Core objects
| Object | Owns | Start here when |
|---|---|---|
| Account state | Identity, managed model and sandbox access, CLI tokens, model defaults, Slack installs, connections, MCP definitions | sign-in, model, billing, token, Slack, or connection state looks wrong |
| GitHub installation | App-backed coverage for one GitHub user or org | repos are visible but GitHub events do not trigger work |
| Repo | Imported repository state and repo-specific settings | the target repo is missing, duplicated, hidden, or needs runtime settings |
| Agent | Reusable behavior, slug, prompt, model, skills, rules, and context | the worker itself behaves wrong or a mention slug does not resolve |
| Route | The rule that decides what wakes work | the wrong event, repo, or workflow starts work |
| Run | One execution of Mogplex work | work started and you need status, events, or final state |
| Mission | The coordinated objective and its task plan | Control must divide a larger objective into task identities |
| Task | One planned unit of mission work | a coding unit needs its own branch and checkout |
| Worktree | One task-specific Git checkout, branch, path, and Sandbox binding | a coding task needs isolation, Diff, Rebase, Archive, or Prune |
| Sandbox | Remote compute for commands, previews, and Worktree checkouts | runtimes, workspace sessions, ports, env, selection, or stale compute are involved |
| Observability record | Captured runtime details | you need calls, tools, errors, tokens, cost, pressure, or sandbox linkage |
Ownership map
| Product area | Primary ownership |
|---|---|
| Settings | account state |
| Installations | GitHub App coverage |
| Slack | Slack workspace install, channel-to-repo links, and Slack-started repo-agent controls |
| Projects | repos, workspace sessions, repo settings, sandbox launch |
| Agents | reusable behavior and mention slugs |
| Triggers | installation-scoped event-to-agent routes |
| Assignments | repo-scoped standing work |
| Automations | workflow graph routing |
| CLI | local run supervision |
| Headless Runs | script and CI execution |
| Sandboxes | cross-repo runtime operations |
| Worktrees | task checkout identity and Git lifecycle |
| Observability | runtime inspection |
The important splits
Visibility vs triggerability
Repo visibility means Mogplex can see a repo through account sync.
Triggerability means the owning GitHub user or org has App-backed coverage, so GitHub webhook events can start hosted work.
A repo can be visible without being triggerable. When that happens, fix GitHub App coverage before editing routes.
Agent definition vs route binding
An agent defines behavior.
A route decides when that behavior runs.
Do not create a new agent when the real problem is that the wrong Trigger, Assignment, or Automation points at it. Do not edit routing when the real problem is an agent slug, model, prompt, skill, rule, or context library.
Run, Worktree, and Sandbox state
A run is the unit of work.
A Worktree is an isolated Git checkout for one planned coding task.
A Sandbox is the remote compute environment the work may use. One Sandbox can host no Worktrees or multiple Worktrees.
Some failures belong to a run. Some belong to a checkout. Others belong to compute or preview. Inspect Observability, Worktrees, and Sandboxes before changing prompts or routing.
Sandbox lifecycle actions never archive or prune Worktrees. Worktree lifecycle actions never stop or delete Sandbox compute. See Control Execution Environments for the complete decision and lifecycle tables.
Interactive vs unattended execution
Use the CLI when a human operator should supervise the work.
Use Headless Runs or the Hosted API when another system should start work unattended.
A route from setup to runtime
- Account state makes the user able to use Mogplex.
- GitHub App coverage makes the repo owner eligible for webhook-backed work.
- Projects imports the repo and stores repo runtime settings.
- Agents define reusable behavior.
- Triggers, Assignments, or Automations bind that behavior to events or repos.
- Slack channel links can also bind a Slack channel to one repo.
- A run starts.
- A mission can create task identities for coordinated Control work.
- A Sandbox can launch or attach when the work needs compute.
- A planned coding task can create a Worktree in that selected Sandbox.
- A worker uses the Worktree's exact checkout path.
- Observability captures the runtime and resource story.
If the chain breaks, debug the earliest missing object first.