# Welcome to Mogplex (/)
Mogplex is an agent workbench for software teams. These docs are organized by
how the product is used: platform areas, capabilities, configuration,
integrations, guides, and reference.
The web app, CLI, hosted API, and extension paths are still documented in full,
but they are not the main decision tree. Start from the job you are trying to
finish, then drill into the product surface that owns it.
Fetch the complete docs index at [`/llms.txt`](/llms.txt). Use
[`/llms-full.txt`](/llms-full.txt) when you need the full text of every docs
page for an agent or external reader.
## Start here [#start-here]
## Product map [#product-map]
## Core capabilities [#core-capabilities]
## Configure and extend [#configure-and-extend]
## Connect your stack [#connect-your-stack]
## Reference paths [#reference-paths]
## The shortest reliable first-day path [#the-shortest-reliable-first-day-path]
1. Open the [web app](/web) and connect GitHub in [Settings](/web/settings).
2. Confirm the right user or org has Mogplex GitHub App coverage in
[Installations](/web/installations).
3. Sync repos and open the target repo in [Projects](/web/spaces).
4. Check or create the reusable agents you want in [Agents](/web/agents).
5. Choose the smallest routing surface that fits the job:
[Triggers](/web/triggers), [Assignments](/web/assignments), or
[Automations](/web/automations).
6. Install the [CLI](/cli/installation), run `mogplex`, and start a local task
in the repo.
7. Use [Observability](/web/observability) once work is actually running.
## What working should mean [#what-working-should-mean]
After the first hour, these should all be true:
* Mogplex can see the repos you expect.
* The repo owner has GitHub App coverage, not only OAuth visibility.
* At least one reusable agent is configured the way you expect.
* One local CLI run completes successfully.
* You know whether the next job belongs in Triggers, Assignments, or
Automations.
If one is still false, start with the [Quickstart](/quickstart),
[Settings](/web/settings), [Installations](/web/installations),
[Mogplex App](/web), or [Mogplex CLI](/cli), depending on where the setup
breaks.
# Plans & Billing (/plans-and-billing)
Mogplex plans and billing docs are coming soon.
This page is a placeholder so pricing, entitlement, usage-limit, invoice, and
billing setup links have a stable home while the billing surface ships.
Detailed plan comparison, account billing, included model usage, managed
sandbox access, usage limits, invoices, payment method management, and team
billing controls will be documented here when they are available.
Mogplex is moving to managed billing for hosted work. That means hosted model
access and sandbox access come from the Mogplex account plan rather than
external model credentials or external sandbox accounts.
## What will live here [#what-will-live-here]
* plan tiers and included usage
* how hosted runs, CLI runs, and account usage are counted
* where admins manage payment methods and invoices
* how usage limits and overages behave
* how managed model and sandbox access are included in each plan
* which roles can view or change billing state
## What to use today [#what-to-use-today]
* Use [Settings](/web/settings) for account setup, access tokens,
connections, and shared preferences.
* Use [Available Models](/web/models) for model availability, enabled models,
defaults, account access, and CLI sync behavior.
* Use [Observability](/web/observability) to inspect run health, model calls,
tokens, and estimated cost.
* Use [CLI Cost & Usage](/cli/reference/cost-and-usage) for local cockpit
token and cost reporting.
## Read next [#read-next]
# Quickstart (/quickstart)
Use this path when you want the first credible Mogplex setup for one repo.
The goal is not to configure every capability. The goal is to prove that
Mogplex can see the repo, has the right GitHub App coverage, can run locally,
and can route the next hosted job through the smallest surface that fits.
## 1. Connect the account [#1-connect-the-account]
Open [Settings](/web/settings), sign in, and connect the account state Mogplex
needs before it can do useful work:
* GitHub identity
* GitHub App coverage for the user or org that owns the repo
* plan-backed model access
* managed sandbox access when the repo needs previews or workspaces
* CLI access tokens if you plan to use the terminal cockpit
* Slack workspace and channel links if work should start from Slack
* shared connections and MCP definitions, if the repo needs external tools
If a repo is visible through OAuth but not covered by the GitHub App, hosted
routing will still fail later. Use [Installations](/web/installations) to
confirm coverage before debugging triggers or automations. The
[GitHub integration guide](/integrations/github) explains the full setup model.
## 2. Open the repo [#2-open-the-repo]
Go to [Projects](/web/spaces), sync repos, and open the target repo.
That repo surface is where hosted work starts. From there, check that the repo
appears once, belongs to the expected owner, and has the coverage state you
expect. If the repo needs sandbox-backed previews, confirm the account plan has
managed sandbox access before debugging workspace launch.
## 3. Check agents and models [#3-check-agents-and-models]
Open [Agents](/web/agents) and confirm at least one reusable agent is ready for
the job. Use [Available Models](/web/models) if model pickers, agents,
automations, or CLI runs do not show the models you expect.
Use [Agent Authoring](/configure-and-extend/agent-authoring) when the agent's
job, slug, prompt, model, rules, or routing fit is still unclear. Use
[Model Selection and Cost](/guides/model-selection-and-cost) before connecting
a high-volume route to a model choice.
## 4. Choose the smallest routing surface [#4-choose-the-smallest-routing-surface]
Use the lightest surface that matches the job:
| Job shape | Start here |
| ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| One GitHub event should wake one agent | [Triggers](/web/triggers) |
| One repo owns recurring or standing work | [Assignments](/web/assignments) |
| The work needs branching, delays, drafts, or parallel agents | [Automations](/web/automations) |
| The event starts in GitHub and you need a recipe | [GitHub Routing Cookbook](/guides/github-routing-cookbook) |
| The request starts from Slack | [Slack](/integrations/slack) |
| You are not sure yet | [Choose the Right Routing Surface](/web/guides/choose-routing-surface) |
## 5. Run locally [#5-run-locally]
Install the [Mogplex CLI](/cli/installation), then run:
```bash
mogplex
```
The CLI opens the terminal cockpit for live agents, timeline events, approvals,
diffs, MCP, memory, model selection, cost, and run control.
For scripted or CI-driven work, use [Headless Runs](/cli/automation/headless-runs)
instead of the interactive cockpit. Use [API Quickstart](/web/api/quickstart)
when another system should start and inspect runs directly.
## 6. Verify the run [#6-verify-the-run]
Use [Observability](/web/observability) once work is running. A healthy first
pass should show:
* the repo you expected
* the surface that started the work
* model calls and token usage
* tool calls and sandbox activity when relevant
* enough status detail to understand whether the run is active, blocked,
complete, or failed
## Read next [#read-next]
# Support (/support)
Use this page when something is not working and you need the fastest path to
the surface that owns the state.
Mogplex issues usually become easier to debug once you separate account setup,
repo coverage, routing, execution, and local CLI state.
## Start with the symptom [#start-with-the-symptom]
| Symptom | Start here |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Repo is visible but GitHub events do not start work | [GitHub](/integrations/github) and [Installations](/web/installations) |
| A model is missing from a picker or CLI run | [Available Models](/web/models) and [Model Selection and Cost](/guides/model-selection-and-cost) |
| Hosted run cannot call an external service | [Connections and MCP](/configure-and-extend/connections-and-mcp), [Settings](/web/settings#connections), and [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides) |
| Slack mention does not start repo work | [Slack](/integrations/slack), [Settings](/web/settings#slack), and [Observability Runbook](/guides/observability-runbook) |
| Sandbox or preview launch is failing | [Sandbox Setup Checklist](/guides/sandbox-setup-checklist), [Vercel](/integrations/vercel), [Projects](/web/spaces), and [Sandboxes](/web/sandboxes) |
| CLI signs in but does not inherit expected hosted state | [Settings](/web/settings), [CLI Authentication](/cli/guides/authentication), and [Configuration and Flags](/cli/guides/configuration-and-flags) |
| A slash command does not behave as expected | [Slash Commands](/cli/commands), [Slash Commands guide](/cli/guides/slash-commands), and [Custom Slash Commands](/configure-and-extend/custom-slash-commands) |
| You need the API error shape or status code | [API Quickstart](/web/api/quickstart) and [API Errors](/web/api/errors) |
| You need to know what is safe to share | [Security and Data Handling](/reference/security-and-data-handling) |
| A doc link or claim looks wrong | [Docs source](https://github.com/webrenew/mogplex-docs) |
For a longer decision tree, use [Troubleshooting](/guides/troubleshooting).
## First checks [#first-checks]
Before changing routing or agent configuration, check these in order:
1. [Settings](/web/settings): GitHub identity, App coverage, managed access,
CLI tokens, and shared connections.
2. [Installations](/web/installations): whether the repo owner has App-backed
coverage.
3. [Projects](/web/spaces): whether the repo is imported once, covered, and
configured for the right runtime.
4. [Available Models](/web/models): whether the expected model is enabled and
available for the account.
5. [Observability](/web/observability): whether the failing run, model call,
tool call, or sandbox event exists.
If there is no relevant Observability record, debug the source surface first:
GitHub, Projects, Triggers, Assignments, Automations, CLI, or API.
## What to capture [#what-to-capture]
When you ask someone else to help diagnose a Mogplex issue, include:
* the repo owner/name
* whether the repo is visible in Projects
* whether the repo owner is covered in Installations
* the surface that started the work, such as CLI, Trigger, Assignment,
Automation, API, Slack, or GitHub mention
* the run ID, sandbox ID, or API request details when available
* the model selected and whether it appears in Available Models
* the exact GitHub comment, mention, event, or CLI command that should have
started work
* the first error message, status, or failed API response, not only the last
retry
## Docs issues [#docs-issues]
The docs source lives in
[webrenew/mogplex-docs](https://github.com/webrenew/mogplex-docs). If a page is
stale, missing a route, or points at the wrong product surface, use the page's
GitHub link or the repository itself as the source path for a docs fix.
## Read next [#read-next]
# Agents (/capabilities/agents)
Agents are reusable workers.
Define them once in the app, then bind them to Triggers, Assignments,
Automations, CLI work, or mention routing.
## What an agent defines [#what-an-agent-defines]
| Part | Why it matters |
| -------------------- | -------------------------------------------------------------------- |
| Name and description | Human-readable identity in pickers and lists |
| Slug | Durable mention handle for `@mogplex/` routing |
| Category | Roster organization and hygiene |
| Model | The default model for that agent, constrained by the account catalog |
| System prompt | The core behavior the agent should follow |
| Skills | Reusable procedures, tools, prompts, and workflows |
| Rules | Shared instruction blocks and policy constraints |
| Context | Reusable memory and background knowledge |
The roster can include built-in presets, owned custom agents, and forks of
presets you have customized.
## When to create or fork an agent [#when-to-create-or-fork-an-agent]
Create or fork an agent when the behavior should be reused across more than one
run, repo, or route.
Good examples:
* PR reviewer
* issue triage assistant
* CI failure investigator
* frontend implementation agent
* docs maintainer
* release checklist runner
If the behavior only changes one step inside one workflow, use an Automation
node override instead of creating a separate agent.
## Slugs and mentions [#slugs-and-mentions]
For GitHub mentions, the slug is the routing identity.
```text
@mogplex
@mogplex/triage
@mogplex/frontend-review
```
Bare `@mogplex` routes only to the default mention route. Targeted
`@mogplex/` mentions route to the agent slug configured on the trigger or
automation entry path.
Keep slugs short, lowercase, and obvious from the job.
## Model hygiene [#model-hygiene]
Agent models are constrained by the live account model catalog.
If an agent was created before a model was hidden, disabled, or renamed, the
agent can still exist on that older model. When you edit long-lived agents,
check [Available Models](/web/models) and move them to a visible enabled model
when appropriate.
## How agents connect to routing [#how-agents-connect-to-routing]
* [Triggers](/web/triggers) wake one agent from one GitHub event.
* [Assignments](/web/assignments) bind one repo, one agent, and one standing
work type.
* [Automations](/web/automations) orchestrate one or more agent nodes in a
workflow graph.
* [Headless Runs](/platform/headless-runs) can start work from scripts and CI.
* [Mogplex CLI](/platform/cli) can supervise local runs with model, approval,
diff, memory, and MCP controls.
## Read next [#read-next]
# Capabilities (/capabilities)
Capabilities are the jobs Mogplex performs for a team. Use this section when
you already know the kind of work you want and need the right product surface.
## Choosing a capability [#choosing-a-capability]
If the work is a reusable worker, start with [Agents](/capabilities/agents). If
the work is about deciding what should run, start with
[Routing](/capabilities/routing). If the work is PR review, issue triage, CI
failure response, or GitHub mentions, start with
[Review and Triage](/capabilities/review-and-triage).
Use [Observability](/capabilities/observability) after work starts, not before
the account and repo setup are healthy.
Use [Model Selection and Cost](/guides/model-selection-and-cost) when the
capability is healthy but the model, repo exclusion, route volume, or cost
policy needs a clearer operating rule.
## Deep dives [#deep-dives]
# Observability (/capabilities/observability)
Observability is how you understand work after it starts.
Use it for runtime questions, not setup questions.
## What it answers [#what-it-answers]
* did the work run?
* is work pending, deferred, suppressed, running, failed, repaired, or
complete?
* which surface started it: CLI, cloud, automation, or live activity?
* which model calls happened?
* what tools were called?
* how many tokens were used?
* what was the estimated cost?
* did the run touch a sandbox?
* what error was captured?
## Read summary before detail [#read-summary-before-detail]
Start with the summary cards to understand the shape of the problem:
* run counts and success rate
* stale pending work
* suppressed and deferred starts
* start failures
* token usage
* estimated cost
* sandbox time
Then open Activity rows for the event timeline, tool calls, raw metadata,
sandbox linkage, GitHub links, and error strings.
## Surface badges [#surface-badges]
| Badge | Meaning |
| ---------- | ------------------------------------------------ |
| Live | The call is still pending or streaming |
| CLI | The call came from the local CLI runtime path |
| Cloud | The call ran outside a job-backed automation |
| Automation | The call is attached to an automation or job run |
This is the fastest way to tell whether a failure or spend spike came from
local work, hosted work, or automation.
## When not to start here [#when-not-to-start-here]
Do not start in Observability when no work has actually queued or started.
If a route did not fire, check the source:
* [Settings](/web/settings)
* [Installations](/web/installations)
* [Projects](/web/spaces)
* [Triggers](/web/triggers)
* [Assignments](/web/assignments)
* [Automations](/web/automations)
* [CLI](/platform/cli)
Observability can explain runtime behavior. It cannot prove why a route that
never emitted a run did not route.
## Common workflows [#common-workflows]
### A run failed [#a-run-failed]
1. Filter Activity by failed status.
2. Open the row for the failing call.
3. Read the captured error and event timeline.
4. Inspect tool calls before changing routing or agent prompts.
### Spend jumped [#spend-jumped]
1. Read token and cost summary cards.
2. Filter by surface.
3. Open high-token or high-cost calls.
4. Compare model, task, tool usage, and sandbox linkage.
### A sandbox preview is unhealthy [#a-sandbox-preview-is-unhealthy]
1. Start from [Sandboxes](/web/sandboxes) if you know the runtime.
2. Jump into Observability with the sandbox context selected.
3. Open the linked call or job row and inspect metadata.
## Read next [#read-next]
# Review and Triage (/capabilities/review-and-triage)
Review and triage are the most common hosted Mogplex workflows.
They share setup, but they should not use the same agent role by default.
## Pick the right job shape [#pick-the-right-job-shape]
| Job | Best starting surface |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Every PR in one repo should be reviewed | [Assignments](/web/assignments) |
| Every PR event in one installation should wake a reviewer | [Triggers](/web/triggers) |
| Review should branch into an edit step only when findings are real | [Automations](/web/automations) |
| New issues need labeling, reproduction guidance, or routing | [Assignments](/web/assignments) or [Triggers](/web/triggers) |
| A human wants to ask from a PR or issue thread | [GitHub mention routing](/web/guides/github-mention-routing) |
| CI failure should be investigated and optionally fixed | [Assignments](/web/assignments), [Triggers](/web/triggers), or [Automations](/web/automations) |
## Agent roles [#agent-roles]
Use `review` when the agent should inspect code changes and produce findings.
Use `triage` when the agent should understand a thread or event, classify it,
respond, label, or decide the next step.
Use `edit` when the graph has already decided code should be changed.
That split keeps mutation explicit. A reviewer can report findings, while a
follow-up edit node can apply changes only after the workflow decides it should.
## Common patterns [#common-patterns]
### Standing PR review [#standing-pr-review]
Use an [Assignment](/web/assignments) when one repo should always use the same
review behavior. This keeps the repo as the durable unit of responsibility.
### Lightweight event review [#lightweight-event-review]
Use a [Trigger](/web/triggers) when a GitHub event should wake one review agent
without a workflow graph.
### Review then fix [#review-then-fix]
Use an [Automation](/web/automations) when the route should:
* review first
* branch on whether findings are real
* edit only on the fix branch
* keep draft changes separate until the workflow is published
### Issue triage [#issue-triage]
Use a `triage` agent for new issues and issue comments. The agent should
classify, summarize, request missing information, route, or answer. It should
not be forced into code-review behavior unless the issue explicitly carries a
diff or reproduction branch.
### GitHub mentions [#github-mentions]
Use exact mention syntax:
```text
@mogplex summarize the failing check
@mogplex/triage label this and suggest next steps
@mogplex/reviewer review this diff with extra attention to auth
```
For targeted mentions, the part after `/` must match an agent slug.
## After work starts [#after-work-starts]
Use [Observability](/web/observability) to answer:
* did the job run?
* did it fail, defer, suppress, or queue?
* what model and tools were used?
* what did it cost?
* which sandbox or GitHub object was involved?
If no run exists, go back to [Routing](/capabilities/routing) and check setup
before inspecting runtime detail.
## Read next [#read-next]
# Routing (/capabilities/routing)
Routing is how Mogplex decides what should run, where it should run, and which
agent should own the work.
The most reliable rule is: start with the smallest surface that can express the
job.
## Routing surfaces [#routing-surfaces]
| Surface | Use it when |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [Triggers](/web/triggers) | One GitHub event should wake one agent for one installation |
| [Assignments](/web/assignments) | One repo owns standing work such as PR review, triage, CI failure response, or cron |
| [Automations](/web/automations) | One event should start a workflow graph with branches, delays, joins, parallel agents, drafts, or publishing |
| [GitHub mentions](/web/guides/github-mention-routing) | A PR or issue comment should wake Mogplex with `@mogplex` or `@mogplex/` |
| [Slack](/integrations/slack) | A Slack DM or channel mention should reply conversationally or start repo-agent work from a linked channel |
| [Headless Runs](/platform/headless-runs) | A script, CI job, or dashboard should start work directly |
| [Mogplex CLI](/platform/cli) | A human should supervise a local run interactively |
## Decision path [#decision-path]
1. If a human is actively operating inside a repo, use the CLI.
2. If another system should start work directly, use a headless run or the API.
3. If Slack should start the work, decide whether the message is conversational
or should route through a linked channel into one repo.
4. If GitHub should start the work, decide whether the durable unit is the
installation, the repo, or a workflow graph.
5. Use Triggers for installation-scoped event routing.
6. Use Assignments for repo-owned standing work.
7. Use Automations when the route needs graph behavior.
The detailed picker is [Choose the Right Routing Surface](/web/guides/choose-routing-surface).
## Mention routing [#mention-routing]
Mention routing is exact:
```text
@mogplex
@mogplex/triage
```
`@mogplex triage` is not a targeted mention. It is a bare mention with text
after it.
Bare mentions need a default mention route. Targeted mentions need an agent
slug match.
Slack mention routing is channel-scoped instead. A linked channel makes
`@mogplex` start repo-agent work for the linked repo; an unlinked channel stays
conversational. See [Slack](/integrations/slack).
## Setup before routing [#setup-before-routing]
Most routing failures are setup failures. Check these before changing the
route:
1. GitHub identity and account state in [Settings](/web/settings)
2. GitHub App coverage in [Installations](/web/installations)
3. repo import state in [Projects](/web/spaces)
4. agent slug and model state in [Agents](/web/agents)
5. route enabled or published state on the source surface
Only use [Observability](/web/observability) after a run exists. If no run
exists, debug the route source first.
## Common upgrades [#common-upgrades]
* Trigger -> Assignment: the route should belong to one repo, not the whole
installation.
* Trigger -> Automation: one event needs branching, delays, or multiple agents.
* Assignment -> Automation: standing repo work needs multi-step control.
* Automation -> Trigger: the workflow graph only wakes one agent and has no
useful draft or publish lifecycle.
## Read next [#read-next]
# Overview (/cli)
The Mogplex CLI (`mogplex`) is a terminal-native command center for supervising AI coding runs.
It is not a log viewer. It is the operator cockpit for everything happening on a run: the agents working on it, the timeline of events, the MCP servers in use, the memory being read and written, the diffs being produced, the tool calls waiting for approval, and the cost and tokens being burned.
```
agents · runs · tools · MCP servers · context · memory
diffs · cost · tokens · model routing · approval gates · process control
```
## Where the CLI fits [#where-the-cli-fits]
* **Web app** is the shared control plane: GitHub coverage, repo setup, reusable agents, hosted runs, routing, settings.
* **CLI** is the persistent terminal cockpit you sit in front of while a run is happening — start it, watch it, steer it, approve it, kill it.
The CLI consumes structured events from the Mogplex core and sends commands back. It does not spawn Claude Code or Codex directly; it observes and controls runs that core orchestrates.
## What the CLI shows [#what-the-cli-shows]
The screen is split into panels you can focus and drawers you can open:
* **Header** — repo, branch, model, mode, run status, dirty flag, permission mode, transport health
* **Agents** — every agent on the active run with status, model, current action
* **Timeline** — structured events streaming in
* **Context & Memory** — what's loaded, what's been written
* **MCP strip** — which MCP servers are ready
* **Command input** — slash commands and composer
* **Priority alerts** — things you should not miss
Drawers cover the deep views: diffs, approvals, MCP detail, memory, agent detail, model picker, cost, run export, and a command palette for everything else.
See [Reference → Panels](/cli/reference/panels) and [Reference → Drawers](/cli/reference/drawers).
## What the CLI is best at [#what-the-cli-is-best-at]
* Watching a run end-to-end without leaving the terminal.
* Approving or rejecting tool calls as they happen.
* Switching models, pausing, resuming, killing, exporting a run.
* Attaching to an in-flight run that started somewhere else (`--attach `).
## Files the CLI reads [#files-the-cli-reads]
* `~/.mogplex/auth.json` — Mogplex token and compatibility auth state.
* `~/.mogplex/permissions.json` — global permission mode and rules.
* `~/.mogplex/projects//permissions.json` — project-level overrides.
* `~/.mogplex/logs/` — structured session logs (secrets redacted).
## Slash commands at a glance [#slash-commands-at-a-glance]
`/run `, `/pause`, `/resume`, `/kill`, `/agents`, `/mcp`, `/diff`, `/memory`, `/model`, `/cost`, `/export`, `/help`, `/clear`, `/quit` (alias `/exit`).
Full reference: [Slash commands](/cli/commands).
## Read next [#read-next]
* [Installation](/cli/installation)
* [Quickstart](/cli/quickstart)
* [Concepts → Architecture](/cli/concepts/architecture)
* [Concepts → Permissions](/cli/concepts/permissions)
* [Concepts → Attach](/cli/concepts/attach)
# Installation (/cli/installation)
Use the hosted installer to download the current release for your platform. No Node.js runtime is required.
## Install [#install]
```bash
curl -fsSL https://www.mogplex.com/install.sh | sh
```
```powershell
iwr -useb https://www.mogplex.com/install.ps1 | iex
```
The PowerShell installer currently targets Windows x64. Windows ARM64 is not
supported yet.
## What the installer changes [#what-the-installer-changes]
The installer downloads the current release archive, extracts the `mogplex` binary, and installs it into the Mogplex home bin directory:
* macOS and Linux: `~/.mogplex/bin/mogplex`
* Windows: `%USERPROFILE%\.mogplex\bin\mogplex.exe`
It then tries to make `mogplex` runnable immediately:
* on macOS and Linux it first tries to link `mogplex` into a writable directory already on your `PATH`
* if that is not possible, it updates your shell profile or prints the export command
* on Windows it updates the user `PATH` for future PowerShell sessions
If you want a different install location, set `MOGPLEX_INSTALL_DIR` before running the installer.
## Installer environment variables [#installer-environment-variables]
* `MOGPLEX_INSTALL_DIR` — override the install location.
* `MOGPLEX_VERSION` — pin to a specific release instead of the latest.
* `MOGPLEX_BASE_URL` — override the manifest host (must be HTTPS).
Examples:
```bash
MOGPLEX_INSTALL_DIR="$HOME/.local/bin" \
curl -fsSL https://www.mogplex.com/install.sh | sh
```
```bash
MOGPLEX_VERSION=0.2.0 \
curl -fsSL https://www.mogplex.com/install.sh | sh
```
## Verify the install [#verify-the-install]
```bash
mogplex --version
```
If your current shell still does not see it, run:
```bash
rehash
# or
exec zsh -l
```
## First run [#first-run]
```bash
mogplex
```
The first launch opens the in-app login screen. Sign in with your Mogplex
account. Mogplex never requires environment variables for normal use.
For the full first-run flow, continue with [Quickstart](/cli/quickstart).
## Upgrade [#upgrade]
Re-run the installer. It detects the existing install and replaces the binary in place.
## Troubleshooting [#troubleshooting]
* `mogplex: command not found` — the install succeeded but your shell has not picked up the updated `PATH`. Rehash or open a new shell.
* The installer downloads but fails before extraction — confirm your machine has the right extractor (`tar` for `.tar.gz`, `unzip` or `ditto` for `.zip`).
* You pinned `MOGPLEX_BASE_URL` and the script exits immediately — the installer rejects non-HTTPS hosts.
* Login succeeds but prompts fail — your account probably lacks model access.
Check [Available Models](/web/models) and [Plans & Billing](/plans-and-billing).
## Uninstall [#uninstall]
Delete the `mogplex` binary from the location the installer reported. Local state in `~/.mogplex/` is left untouched.
Remove that directory too if you want to clear config, auth, logs, permissions, and other local state.
# Quickstart (/cli/quickstart)
The shortest useful loop:
1. install the binary
2. start `mogplex`
3. sign in (in-app)
4. start a run with `/run`
5. watch agents and timeline; approve or kill as needed
## 1. Install [#1-install]
See [Installation](/cli/installation).
## 2. Start the cockpit [#2-start-the-cockpit]
```bash
mogplex
```
If you are not authenticated, the in-app login screen appears. Pick one:
* **Sign in with Mogplex** — opens a browser for account-backed login. This
reuses your plan-backed model access, synced model catalog, and remote MCP
definitions.
Stored credentials live in `~/.mogplex/auth.json` (file mode `0600`).
The CLI ships to end users — auth and config are in-app. Environment
variables exist as escape hatches only. See
[Configuration and Flags](/cli/guides/configuration-and-flags).
## 3. Start a run [#3-start-a-run]
In the composer:
```text
/run review the staged diff for regressions
```
The Agents panel populates as core spawns workers. The Timeline streams structured events. The Header shows model, mode, run status, and transport health.
## 4. Drive the run [#4-drive-the-run]
| Action | Command |
| ------------------- | ------------------------------ |
| Pause / resume | `/pause` then `/resume` |
| Kill the run | `/kill` |
| Switch models | `/model` (opens picker drawer) |
| Open the diff | `/diff` |
| See cost so far | `/cost` |
| Open MCP detail | `/mcp` |
| Inspect memory | `/memory` |
| Export the run | `/export` |
| List slash commands | `/help` |
| Quit | `/quit` (alias `/exit`) |
Full reference: [Commands](/cli/commands).
## 5. Approvals [#5-approvals]
If the active permission mode is `approval` (the default), tool calls that touch the workspace pause and surface in the Approval drawer. Approve or reject inline. See [Concepts → Approvals](/cli/concepts/approvals) and [Concepts → Permissions](/cli/concepts/permissions).
## 6. Attach to an in-flight run [#6-attach-to-an-in-flight-run]
If a run was started somewhere else (web app, CI, another shell), you can pull up its cockpit with:
```bash
mogplex --attach
```
See [Concepts → Attach](/cli/concepts/attach).
## What "working" looks like [#what-working-looks-like]
* `mogplex` opens cleanly to the cockpit (or to the login screen on first run).
* Header shows `transport: nominal` once core is connected.
* `/run ` produces agents in the Agents panel and events in the Timeline.
* Approvals appear in the Approval drawer when the run touches the workspace.
* Ctrl+C does **not** quit — it logs a soft-interrupt. Press it twice within 1500ms (or type `/quit`) to exit.
## Common first-run issues [#common-first-run-issues]
* Login succeeds but no models available — check [Available Models](/web/models)
and the account plan. Account-backed login inherits managed hosted access.
* Header says `transport: offline` — core is unreachable. Check network and retry; the daemon transport surfaces a reconnect banner.
* A slash command "doesn't work" — check `/help` for the actual registry.
## Read next [#read-next]
* [Concepts → Architecture](/cli/concepts/architecture) for the mental model.
* [Concepts → Permissions](/cli/concepts/permissions) for `approval` vs `auto` modes.
* [Reference → Keybindings](/cli/reference/keybindings) for focus rotation and exit behavior.
* [Guides → Authentication](/cli/guides/authentication) for credential precedence.
# Agent Authoring (/configure-and-extend/agent-authoring)
An agent is a reusable worker, not a one-off task ticket.
Use this page when you are creating or editing agents that will be bound to
Triggers, Assignments, Automations, GitHub mentions, CLI workflows, or API
started work.
## Start with the contract [#start-with-the-contract]
Before writing a long system prompt, define the agent contract:
| Field | Question to answer |
| ---------------------- | --------------------------------------------------------------------------- |
| Job | What durable kind of work does this agent own? |
| Scope | Which repos, routes, or event types should use it? |
| Inputs | What context should it expect from GitHub, CLI, API, or automation state? |
| Outputs | Should it comment, summarize, review, edit, open a branch, or ask for help? |
| Authority | What may it change without extra human instruction? |
| Model | Does the job need stronger reasoning, lower cost, or long context? |
| Slug | How will humans target it with `@mogplex/`? |
| Skills, rules, context | What should be reusable instead of copied into the prompt? |
If the contract is unclear, routing will be unclear too.
## Good agent shapes [#good-agent-shapes]
Good agents are narrow enough to evaluate:
* PR reviewer
* issue triage assistant
* CI failure investigator
* docs maintainer
* frontend implementation agent
* release checklist runner
* migration planner
Weak agents are broad and hard to route:
* "general engineer"
* "do everything"
* "repo expert"
* "AI assistant"
Broad agents are still useful for manual CLI work, but they make hosted
routing harder to debug.
## Slugs [#slugs]
Slugs are routing identifiers for targeted GitHub mentions.
```text
@mogplex/triage
@mogplex/review
@mogplex/docs
```
Use slugs that are:
* short
* lowercase
* stable
* job-shaped
* unambiguous to a teammate reading a GitHub comment
Avoid encoding model names, temporary projects, or people in slugs. Those
change more often than the agent's job.
## Prompt structure [#prompt-structure]
Use a compact structure:
```text
You are the agent for .
Primary goal:
- ...
Inputs you may receive:
- ...
How to work:
- ...
When to ask for help:
- ...
Output expectations:
- ...
```
Keep routing instructions out of the prompt when the route itself can own them.
For example, an Automation should own graph steps and conditions. The agent
prompt should own behavior inside its node.
## Skills, rules, and context [#skills-rules-and-context]
Use [Skills, Rules, and Context](/web/agents/skills-rules-context) to avoid
prompt bloat:
| Reusable layer | Use it for |
| -------------- | ---------------------------------------------------------- |
| Skills | Procedures or capabilities the agent can invoke on demand |
| Rules | Team or repo policies the agent should follow consistently |
| Context | Background knowledge that should be available across runs |
If you paste the same paragraph into multiple agents, it probably belongs in a
rule, skill, or context entry.
## Model choice [#model-choice]
Set the model on the agent when the job has a durable model requirement.
Examples:
* use a stronger model for security review or difficult implementation
* use a lower-cost model for high-volume triage
* use a long-context model for large codebase reading
For one-off differences inside a workflow, prefer an Automation node override
instead of creating another nearly identical agent.
Read [Model Selection and Cost](/guides/model-selection-and-cost) before
changing a high-volume route.
## Forking presets [#forking-presets]
Fork or customize a preset when:
* the built-in job is close but your repo needs different output
* an Assignment should own a durable copy of the behavior
* the model, prompt, slug, rules, or context need to become account-owned
Do not fork just to handle one temporary instruction. Put temporary detail in
the prompt for that run, assignment, or automation node.
## Routing fit [#routing-fit]
| Route | Agent authoring implication |
| ---------- | -------------------------------------------------------------------- |
| Trigger | The agent should handle one event cleanly with minimal orchestration |
| Assignment | The agent should be durable for one repo and one standing work type |
| Automation | The agent should own one node role, not the whole graph |
| Mention | The slug and response behavior must be obvious to humans |
| CLI | The agent can be broader because a human is supervising the run |
| API run | The prompt and request body must provide the missing route context |
## Review checklist [#review-checklist]
Before saving a durable agent:
* the name explains the job
* the slug matches the targeted mention you expect
* the description helps a teammate pick it from a list
* the model is deliberate
* the prompt says what to do and when to stop
* the output expectation is explicit
* shared rules are not duplicated in the prompt
* routing-specific behavior is owned by the route when possible
* one small test run succeeds before connecting a high-volume route
## Read next [#read-next]
# Connections and MCP (/configure-and-extend/connections-and-mcp)
Connections are how Mogplex agents reach external systems.
They are separate from managed model access, GitHub App coverage, Slack channel
links, and the preview path where other MCP clients call into Mogplex.
## Direction matters [#direction-matters]
There are three MCP-related surfaces with different directionality:
| Surface | Direction | Use it for |
| ---------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
| Connections | Mogplex calls external REST APIs or MCP servers | Give agents tools such as Linear, Supabase, Notion, or Sentry. |
| [MCP Servers API](/web/api/mcp-servers) | CLI or scripts read your configured external MCP servers | Sync cloud MCP definitions into local agent hosts. |
| [Mogplex MCP server](/extend/mcp-server) | External MCP clients call Mogplex | Preview design path for exposing Mogplex as an MCP server. |
When a hosted run cannot call an external tool, debug Connections. When another
agent host needs to call Mogplex, start with [Skills](/extend/skills) today and
the [Mogplex MCP server preview](/extend/mcp-server) for the future path.
## Connection types [#connection-types]
Mogplex supports two connection categories:
| Type | What you provide | What agents get |
| ---------- | ------------------------------------- | ----------------------------------- |
| REST API | Base URL plus optional auth | A typed external HTTP tool surface. |
| MCP Server | MCP URL or command plus auth material | Tools exposed by the MCP server. |
Manual auth modes include none, API key, bearer token, basic auth, and OAuth.
Connection credentials are stored server-side and resolved only when the
connection is tested, listed for CLI sync, or used by a run.
## Quick-add presets [#quick-add-presets]
Settings includes MCP presets for common tool providers:
| Preset | Typical use |
| ----------- | ------------------------------------------------- |
| Zapier | User-specific actions across connected apps. |
| Notion | Workspace search, pages, databases, and comments. |
| Supabase | Database, auth, storage, and edge functions. |
| Browserbase | Cloud browser automation and scraping. |
| Sentry | Error tracking, performance, and session replay. |
| Sanity CMS | Structured content, media, and releases. |
| Linear | Issues, projects, cycles, and team workflows. |
Some presets use direct credentials. Some use OAuth, including managed auth
where Mogplex brokers the provider flow.
Use presets first when one exists. Use manual Add Connection for advanced MCPs
or REST APIs that do not have a preset yet.
## Scope resolution [#scope-resolution]
Connections can be global or project-scoped.
| Scope | Behavior |
| --------- | ---------------------------------------------------------------- |
| Global | Available to every repo unless that repo excludes it. |
| Project | Available only to one repo. |
| Exclusion | Removes one global connection from one repo without deleting it. |
For a repo, Mogplex resolves runnable connections by starting with enabled
global connections, removing excluded globals, then adding enabled project
connections.
Read [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides)
for the full operating model.
## MCP limits [#mcp-limits]
Mogplex caps enabled MCP server connections at five per resolved scope.
The cap protects runs from receiving an oversized or noisy tool surface. If a
repo reaches the cap, decide whether to:
* disable a connection
* exclude a global MCP from that repo
* move a repo-only tool to project scope
* replace overlapping MCPs with one better-scoped server
Do not add another broad MCP just because a tool call failed. First confirm the
right server is in the resolved set for that repo.
## CLI sync [#cli-sync]
When the CLI is signed in with a Mogplex token, it can fetch your cloud MCP
catalog from:
```text
GET /api/v1/mogplex/mcp/servers
```
The CLI stores the fetched catalog in:
```text
~/.mogplex/mcp-servers.remote.json
```
On startup, the CLI can use the remote list, the cache, or no cloud MCP list if
there is no token and no cache. A network or auth failure can fall back to the
cache so existing local work is not blocked by a transient catalog fetch issue.
Use `/mcp` in the CLI to inspect MCP state during a session.
## Security notes [#security-notes]
* Treat MCP server config responses like `.env` files. They can include
decrypted headers, env vars, or OAuth access tokens.
* Do not paste `/api/v1/mogplex/mcp/servers` output into issues, PRs, or chat
logs.
* Prefer project-scoped connections when credentials only make sense for one
repo.
* Exclude global MCPs from repos where the tool surface would be unsafe or
distracting.
* Reconnect OAuth-backed presets from Settings when authorization expires.
## Troubleshooting [#troubleshooting]
| Symptom | Check |
| --------------------------------------- | -------------------------------------------------------------------------- |
| Tool missing in a hosted run | Confirm the connection is enabled and included in the repo's resolved set. |
| Tool works globally but not in one repo | Check for a project exclusion or a project-specific connection cap. |
| CLI does not show cloud MCP servers | Confirm CLI token login, then inspect `/mcp` and the remote cache file. |
| OAuth preset stopped working | Reconnect it from Settings and retest before changing prompts. |
| MCP response leaks secrets in logs | Rotate the exposed credential and stop logging MCP config output. |
## Read next [#read-next]
# Custom Slash Commands (/configure-and-extend/custom-slash-commands)
Custom slash commands are the repo-local authoring format for repeatable
Mogplex CLI prompts.
Use this page when you are preparing reusable prompt templates or reading files
created by `/init`.
Check `/help` in the running cockpit before relying on a custom command in
production. The markdown loader and authoring format exist in the CLI
runtime packages, and `/init` scaffolds `.agents/commands/review.md`, but
the current cockpit command input still exposes the built-in registry in
some builds.
## Where commands live [#where-commands-live]
The slash-command loader is designed to read commands from project and user
scopes.
Project scope:
```text
/.agents/commands/**/*.md
/.mogplex/commands/**/*.md
```
User scope:
```text
$AGENTS_HOME/commands/**/*.md
$MOGPLEX_HOME/commands/**/*.md
```
`$AGENTS_HOME` is optional. When it is set, Mogplex checks it before
`$MOGPLEX_HOME` for user-scoped commands. `$MOGPLEX_HOME` defaults to
`~/.mogplex`. The `.agents/commands` path is the preferred project path.
`.mogplex/commands` still works as a legacy alias.
Nested directories become namespaced commands:
```text
.agents/commands/release/notes.md -> /release:notes
.agents/commands/deploy.md -> /deploy
```
## Precedence [#precedence]
If the same command name appears in more than one scope, Mogplex keeps the
highest-precedence version:
1. project command
2. user command
3. builtin command
Within project scope, `.agents/commands` wins over `.mogplex/commands`.
Shadowed commands produce diagnostics, but they do not stop the registry from
loading.
## Minimal command [#minimal-command]
Create `.agents/commands/review-staged.md`:
```md
Review the staged git diff for correctness bugs, missing tests, and style
inconsistencies with this repo. Keep the result concise and cite files.
```
When custom command loading is enabled in your build, the command is invoked as:
```text
/review-staged
```
A bare markdown file is valid for the loader. The filename becomes the command
name.
## Frontmatter [#frontmatter]
Add YAML frontmatter when the command needs metadata:
```md
---
description: Review one PR for correctness and test coverage
aliases:
- pr-review
arguments:
- name: pr
kind: positional
required: true
description: Pull request number
model: anthropic/claude-sonnet-4-6
allowed-tools:
- shell
- read_file
available-during-task: false
---
Review pull request #$1. Focus on:
- correctness bugs
- missing tests
- security-sensitive changes
- behavior that contradicts repo conventions
```
Supported frontmatter fields:
| Field | Purpose |
| ----------------------- | --------------------------------------------------- |
| `name` | Override the command name from the filename. |
| `description` | Short text shown in command help. |
| `aliases` | Additional names that invoke the same command. |
| `arguments` | Positional, named, or rest argument declarations. |
| `model` | Model override for the generated turn. |
| `allowed-tools` | Tool allow-list for that turn. |
| `available-during-task` | Whether the command can run while a task is active. |
## Arguments and templates [#arguments-and-templates]
Command bodies support prompt-template placeholders:
| Placeholder | Expands to |
| ------------ | --------------------------------------------------- |
| `$ARGUMENTS` | All positional arguments joined by spaces. |
| `$1`, `$2` | Positional argument by index. |
| `${NAME}` | Named argument value. |
| `$NAME` | Named argument shorthand for uppercase identifiers. |
Example:
```md
---
description: Draft release notes for a tag
arguments:
- name: tag
kind: positional
required: true
- name: audience
kind: named
required: false
default: users
---
Draft release notes for $1. Write for ${audience}. Include breaking changes,
fixes, and upgrade notes from git history.
```
Invocation:
```text
/release-notes v1.4.0 --audience=maintainers
```
## Config aliases and disabled commands [#config-aliases-and-disabled-commands]
The config schema supports slash-command aliases, disabled commands, and extra
directories:
```toml
[slash_commands]
disabled = ["logout"]
extra_dirs = ["/opt/company/mogplex-commands"]
[slash_commands.aliases]
r = "review"
ship = "deploy"
```
Use command-file aliases when the alias should travel with the repo. Use config
aliases only when the target build wires the slash-command loader into the
running cockpit.
## Good command shapes [#good-command-shapes]
Good custom commands are:
* short enough to inspect quickly
* specific to one repeatable workflow
* argument-driven instead of hardcoded to one issue or branch
* safe to run from a teammate's checkout
* free of secrets and personal-only paths
Examples:
* `/review-staged`
* `/write-pr-summary`
* `/release:notes`
* `/debug-failing-test`
* `/triage-issue`
Avoid turning every one-off instruction into a command. If the prompt changes
each time, keep it in chat.
## Verify the active registry [#verify-the-active-registry]
The source of truth for the active cockpit is still `/help`:
```text
/help
```
If a command does not appear there, the running build is not exposing it. Check
the path, YAML frontmatter, command name, shadowing, and whether your build has
custom command loading wired into the cockpit input.
## Read next [#read-next]
# Configure & Extend (/configure-and-extend)
Use this section when Mogplex is visible but not yet behaving the way the repo,
team, or local workflow needs.
## Common configuration paths [#common-configuration-paths]
* Model or account-access issue: start with [Available Models](/web/models), then
check [Model Selection and Cost](/guides/model-selection-and-cost) and
[Settings](/web/settings).
* Durable worker behavior is hard to reuse: start with
[Agent Authoring](/configure-and-extend/agent-authoring), then check
[Agents](/web/agents).
* Repo-local context is being repeated in prompts: start with
[Repo Instructions](/configure-and-extend/repo-instructions), then factor
repeatable composer prompts into
[Custom Slash Commands](/configure-and-extend/custom-slash-commands).
* Agent tools are missing or too broad: start with
[Connections and MCP](/configure-and-extend/connections-and-mcp), then check
[Connection Scope and Overrides](/web/guides/connection-scope-and-overrides).
* Repo is visible but cannot trigger hosted work: start with
[GitHub](/integrations/github) and [Installations](/web/installations).
* Sandbox launch reports missing access: start with
[Plans & Billing](/plans-and-billing), then confirm repo settings in
[Projects](/web/spaces).
* CLI asks for permission unexpectedly: start with
[Permissions](/cli/concepts/permissions) and
[Approvals](/cli/concepts/approvals).
* Another agent host needs to guide a user through Mogplex: start with
[Skills](/extend/skills).
# Repo Instructions (/configure-and-extend/repo-instructions)
Repo instructions are the durable context layer for local Mogplex work.
Use them for facts that should survive across prompts: repo layout, build
commands, verification rules, ownership boundaries, style conventions, and
known workflow constraints.
Do not use them as a scratchpad for one temporary task. The current prompt is
still the right place for volatile instructions.
## What Mogplex reads [#what-mogplex-reads]
The CLI runtime can load two repo-local files:
| File | Purpose |
| ------------ | --------------------------------------------------------------------------- |
| `AGENTS.md` | Markdown instructions injected into the run's system prompt. |
| `agent.json` | Minimal structured project configuration, including prompt suffix metadata. |
`AGENTS.md` is the main file. `agent.json` is useful when a project needs a
small structured override beside the prose instructions.
## Discovery order [#discovery-order]
Mogplex discovers instruction fragments from the current working directory and
the active Mogplex home directory.
The current discovery model is:
1. `$MOGPLEX_HOME/AGENTS.md` for user-level guidance.
2. the git project root's `AGENTS.md`.
3. nested `AGENTS.md` files between the project root and the current working
directory.
Within each directory, `AGENTS.override.md` wins over `AGENTS.md`.
That gives you three useful layers:
| Layer | Best for |
| ------------ | -------------------------------------------------------------- |
| User | Personal operating preferences that should apply across repos. |
| Project root | Repo-wide architecture, commands, and policy. |
| Subproject | Monorepo package-specific setup or verification detail. |
Keep the project-root file broad. Put package-specific exceptions closer to the
package that needs them.
## Session behavior [#session-behavior]
Instruction files are startup context for the run, not live chat messages.
Mogplex assembles the system prompt by combining the base runtime prompt,
discovered `AGENTS.md` fragments, and the supported `agent.json` prompt suffix.
The assembled prompt is cached for the session.
If you change instruction files while a session is already running, treat the
next session as the clean verification point unless the surface you are using
explicitly reloads project configuration.
## Create a starter file [#create-a-starter-file]
In the CLI composer:
```text
/init
```
`/init` asks Mogplex to scan the repo and create:
* `AGENTS.md`
* `.agents/commands/review.md`
Use the generated file as a draft. Read it before trusting it, especially in a
large repo where build and test commands may be conditional.
## Good AGENTS.md content [#good-agentsmd-content]
Good repo instructions are short, operational, and checkable:
```mdx
# AGENTS.md
## Commands
- Install: `pnpm install`
- Lint: `pnpm lint`
- Typecheck: `pnpm types:check`
- Build: `pnpm build`
## Repo Rules
- Use `rg` for source search.
- Keep docs claims grounded in sibling app and CLI repos.
- Do not hand-edit generated command reference files.
- Preserve unrelated dirty worktree changes.
## Verification
- For docs-only edits, run `git diff --check`.
- For TypeScript or MDX structure changes, run `pnpm types:check`.
```
Prefer commands and rules over philosophy. A future run should be able to use
the file without asking what the sentence means.
## `agent.json` [#agentjson]
`agent.json` is a strict JSON object at the project root.
The current schema accepts:
```json
{
"model": "anthropic/claude-sonnet-4-6",
"system_prompt_suffix": "Prefer focused fixes and cite touched files.",
"disabled_tools": ["example-tool"],
"extra_slash_dirs": [".agents/team-commands"],
"personality": "direct"
}
```
Use `system_prompt_suffix` only for short, durable behavior that belongs after
the markdown instructions.
For model routing, managed access, and tool policy, prefer the first-class
Mogplex controls unless the specific surface you are using documents that it
honors the `agent.json` field.
## What not to put here [#what-not-to-put-here]
Avoid:
* secrets, tokens, API keys, or passwords
* task-specific notes that only matter today
* long copied docs from external systems
* instructions that contradict the repo's actual scripts
* broad personality prose that does not change execution
If a sentence cannot guide a future command, edit, test, or review decision, it
probably does not belong in repo instructions.
## Related reusable layers [#related-reusable-layers]
| Layer | Use it for |
| -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `AGENTS.md` | Repo and package instructions for local runs. |
| [Custom Slash Commands](/configure-and-extend/custom-slash-commands) | Reusable prompt templates in the CLI composer. |
| [Agent Authoring](/configure-and-extend/agent-authoring) | Durable hosted agent identity, prompt, slug, and model. |
| [Skills, Rules, and Context](/web/agents/skills-rules-context) | Product-side reusable procedures, policy, and background context. |
| [Assignments](/web/assignments) | Standing repo-owned hosted work. |
## Read next [#read-next]
# Extend (/extend)
Mogplex is usable from two surfaces that ship today: the [web app](/web) and the [CLI](/cli). This section covers the third direction: letting *other* agents reach Mogplex.
The core question is: your teammate is in Claude Code, Cursor, or a custom Claude Agent SDK app, and wants to use their Mogplex skills, memories, or agents from there — without pasting tokens into a JSON config. What should they do?
## Which path is right today [#which-path-is-right-today]
| If the user's agent host… | Use |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Is skill-aware (Claude Code, Agent SDK, Cursor project rules) | [Skills](/extend/skills) |
| Supports remote MCP with OAuth, and the Mogplex MCP server is live | [MCP server](/extend/mcp-server) |
| Needs scripted, headless access to Mogplex | Use the [CLI's automation surface](/cli/automation) (`mogplex run`, `mogplex runs events --follow`) or the [v1 REST API](/web/api) directly. Both ship today. |
Skills are the recommended path until the MCP server is generally available. They teach a skill-aware agent to guide the user through the Mogplex cockpit (slash commands, login flow, repo-local config) without ever needing the user to paste a token.
## How this section relates to the rest of the docs [#how-this-section-relates-to-the-rest-of-the-docs]
* **Inbound MCP** (Mogplex *consuming* external MCP servers like Zapier, Notion, Supabase) is covered in [Connections and MCP](/configure-and-extend/connections-and-mcp). That direction is live today.
* **Outbound MCP** (Mogplex *exposed as* an MCP server to external agents) is covered here at [MCP server](/extend/mcp-server).
* **CLI Skills** documentation lives under [CLI → Skills](/cli/skills). The [Skills](/extend/skills) page in this section is a pointer; the canonical reference is under CLI.
## Design principles this section follows [#design-principles-this-section-follows]
* **No pasted tokens.** Whether the user picks Skills or MCP, the auth flow owns the credential — either the cockpit's in-app login writing to `~/.mogplex/auth.json` (Skills path) or OAuth 2.1 + PKCE against the browser session (MCP path). In both cases the external agent never sees raw auth material.
* **One source of truth per capability.** Tools, agents, skills, and memories are implemented once in the Mogplex runtime. Skills point the user at the cockpit; MCP exposes the underlying services directly.
* **Auth preflight is mandatory.** Both paths require a working credential before any action runs. Skills enforce it with a `command -v mogplex` install check and a recommendation to launch the cockpit; MCP enforces it at the Streamable HTTP bearer-token middleware.
# MCP server (preview) (/extend/mcp-server)
The Mogplex MCP server is in **preview design state** — not generally available. Use [Skills](/extend/skills) today; this page documents the direction of travel so integrators can plan.
## What it is [#what-it-is]
A remote Model Context Protocol server hosted by Mogplex. Any MCP-aware agent host (Claude Code, Cursor, Claude Desktop, opencode, custom Agent SDK apps) will be able to connect and call Mogplex tools, agents, skills, and memories as MCP primitives — without the user pasting a token into a JSON config.
The final endpoint path is not yet committed. Examples on this page use `https://mogplex.com/mcp` as a **placeholder**; the shipping URL (exact host, version prefix) will be announced in release notes and this page will be updated then. Do not wire the placeholder URL into production clients.
## What it replaces [#what-it-replaces]
The substitute available today is the **Skills** approach (see [Skills](/extend/skills)). Skills teach an external agent to drive Mogplex through the `mogplex` CLI. The MCP server path replaces that shim with a direct protocol-native integration once the host supports remote MCP with OAuth.
```
Claude Code / Cursor ──► mogplex.com/mcp (Streamable HTTP, bearer token)
│
▼
Mogplex tool/agent/skill/memory handlers
(same code paths the in-app agent uses)
```
## Auth model [#auth-model]
Spec-compliant MCP OAuth 2.1 + PKCE, reusing the user's existing Supabase session:
* `/.well-known/oauth-protected-resource` on the MCP endpoint.
* `/.well-known/oauth-authorization-server` on the app origin.
* **Dynamic Client Registration** at `/oauth/register` so each client (Claude Code, Cursor, a custom app) provisions its own `client_id` without the user editing any config.
* Short-lived access tokens (1h, audience `mcp`), rotating refresh tokens (30d), stored hashed in Supabase.
* Scopes: `tools:read`, `tools:execute`, `memories:read`, `memories:write`, `agents:run`, `skills:read`, `workspaces:read`. Default grant is read-only; execute and write require explicit consent at the authorize step.
Users manage active clients from **Settings → Connections → Local agents** (revoke, inspect last-used, see requested scopes).
## Tool surface (planned v1) [#tool-surface-planned-v1]
Each tool is a thin adapter over an existing Mogplex service, not a new capability:
* `mogplex_list_workspaces`, `mogplex_get_workspace`
* `mogplex_list_skills`, `mogplex_get_skill`, `mogplex_run_skill`
* `mogplex_list_agents`, `mogplex_run_agent` (streamed progress via MCP notifications)
* `mogplex_search_memories`, `mogplex_add_memory`, `mogplex_edit_memory`
* `mogplex_list_rules`, `mogplex_get_rule`
* `mogplex_run_tool` (generic dispatcher)
Mogplex skills are additionally exposed as MCP **prompts**, since a skill definition maps naturally to that primitive.
## Install (once available) [#install-once-available]
Remote Streamable HTTP — no shim, no token pasting, the host drives OAuth. The shape of the commands below is accurate; the URL is a placeholder that will be finalized when the server ships:
```bash
# Claude Code — replace with the final endpoint from release notes
claude mcp add --transport http mogplex
# Cursor
# Settings → MCP → Add server → URL:
```
For hosts that don't yet speak remote MCP with OAuth, a stdio shim `npx -y @mogplex/mcp` will ship alongside. The shim runs the OAuth flow once, stores the token in `~/.mogplex/auth.json` (same file the CLI uses), and proxies stdio ↔ HTTP.
## How it relates to Connections (inbound MCP) [#how-it-relates-to-connections-inbound-mcp]
Do not confuse the two directions:
| Direction | Where configured | Who authenticates |
| ------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------- |
| **Mogplex consumes an MCP server** (Zapier, Notion, Supabase) | [Connections and MCP](/configure-and-extend/connections-and-mcp) | Mogplex to the external service |
| **Mogplex exposed as an MCP server** | [Settings → Connections → Local agents](/web/settings) (when live) | External agent to Mogplex |
Both can be in use at the same time. An agent running outside Mogplex can call the Mogplex MCP server, and Mogplex can turn around and call a Notion MCP connection from within the same logical tool call.
## Status [#status]
* Design: approved.
* Schema, OAuth endpoints, Streamable HTTP handler, stdio shim: planned, not yet merged.
* Current public substitute: [Skills](/extend/skills) and the [CLI](/cli).
When the server ships, this page will update with the live endpoints, the final scope list, and the Settings UI screenshot. Subscribe to release notes or watch the [mogplex-cli repo](https://github.com/webrenew/mogplex-cli) for the `@mogplex/mcp` package.
## See also [#see-also]
* [Skills](/extend/skills) — today's substitute
* [CLI Skills reference](/cli/skills) — canonical skill files
* [Connections and MCP](/configure-and-extend/connections-and-mcp) — inbound MCP (Mogplex as consumer)
* [MCP specification](https://modelcontextprotocol.io/specification)
# Skills (/extend/skills)
Skills are the currently-shipping path for letting an external agent reach a user's Mogplex capabilities. They are the drop-in substitute for the [MCP server](/extend/mcp-server) until that ships.
The canonical skill files and the per-skill reference pages live under [CLI → Skills](/cli/skills). This page is the entry point from the Extend section — it describes the shape of the set and the trade-offs versus MCP. Go to [/cli/skills](/cli/skills) for the individual skills.
## What the set covers [#what-the-set-covers]
| Skill | Role |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [`using-mogplex-cli`](/cli/skills/using-mogplex-cli) | Umbrella. Guides the user through the Mogplex cockpit when they ask for a workspace action. |
| [`mogplex-slash`](/cli/skills/mogplex-slash) | Recommends the right slash command for a user's intent. |
| [`mogplex-auth`](/cli/skills/mogplex-auth) | Walks the user through the in-app login flow and credential troubleshooting. |
The current Mogplex CLI is interactive-only — these are **guidance skills** that teach an agent to advise the user on cockpit workflows. They do not drive the TUI. When the [MCP server](/extend/mcp-server) ships, that path will give external agents direct programmatic access to Mogplex capabilities without going through the cockpit.
## Why this is the right path today [#why-this-is-the-right-path-today]
* **No pasted tokens.** The cockpit's in-app login flow owns the credential and writes it to `~/.mogplex/auth.json` — see the [Authentication guide](/cli/guides/authentication) for precedence rules and file contents. The external agent never sees raw auth material.
* **Works in every skill-aware host.** The skill format is portable: Claude Code, Claude Agent SDK, and any host that reads `SKILL.md`-style files. Cursor project rules work too by copying the skill body.
* **Thin wrapper.** Skills do not duplicate Mogplex logic — they are instructions for how the user should drive the CLI cockpit, which talks to the existing Mogplex runtime.
* **No infra dependency.** Ships the moment the CLI is on the user's `PATH`. Nothing to deploy, no tokens to provision.
## Skills vs MCP server at a glance [#skills-vs-mcp-server-at-a-glance]
| | Skills (today) | MCP server (preview) |
| ----------------------- | -------------------------------------------------- | ------------------------------------------ |
| Status | **Available** | Preview design; not live |
| Protocol | Skill file (guidance) | MCP Streamable HTTP |
| Auth | In-app login → `~/.mogplex/auth.json` | OAuth 2.1 + PKCE (DCR) |
| Token pasted in config? | No | No |
| Execution path | Agent advises user; user drives the cockpit | External agent calls MCP tool directly |
| Streaming progress | n/a — user watches the cockpit | MCP `notifications/progress` |
| Host requirement | Skill-aware (Claude Code, Agent SDK, Cursor rules) | Remote-MCP-aware with OAuth |
| Host reach today | High | Claude Code ≥ latest, Cursor, a few others |
When the MCP server ships, it becomes the right path for hosts that need programmatic access without involving the user. Skills will continue to be useful for hosts that don't speak remote MCP and for situations where the user is the right one to drive the cockpit.
## Install [#install]
The skills live in [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs) under `skills/`. Pick one fetch method, which sets a `SKILLS` path variable used by the copy step below:
```bash
# Option A — full clone (gives you the rest of the docs repo too)
git clone https://github.com/webrenew/mogplex-docs.git
SKILLS=mogplex-docs/skills
# Option B — sparse download of just the skills/ tree
# degit copies the *contents* of skills/ into mogplex-skills/,
# so mogplex-skills is the skills tree (no nested skills/ dir).
npx -y degit webrenew/mogplex-docs/skills mogplex-skills
SKILLS=mogplex-skills
```
Then copy into your agent host. Both commands run from the same shell where you set `$SKILLS`:
```bash
# Global (Claude Code)
mkdir -p ~/.claude/skills && cp -R "$SKILLS"/* ~/.claude/skills/
# Or per-project (run from your project root)
mkdir -p .claude/skills && cp -R "$SKILLS"/* .claude/skills/
```
See [CLI → Skills](/cli/skills) for Agent SDK integration, Cursor instructions, and the full install matrix.
## See also [#see-also]
* [CLI → Skills](/cli/skills) — canonical reference for every skill
* [MCP server (preview)](/extend/mcp-server) — what Skills are a substitute for
* [Extend overview](/extend) — the decision between Skills and MCP
# Common Use Cases (/guides/common-use-cases)
Use this page when you know the job you want done, but not the Mogplex surface
that should own it.
The fastest path is usually the smallest surface that can express the job. Move
up to a heavier surface only when the workflow needs more structure.
## Review a pull request [#review-a-pull-request]
Start with [Assignments](/web/assignments) when one repo should always use the
same review behavior.
Use [Triggers](/web/triggers) when one GitHub App installation should wake an
agent directly on `pr_opened` or `pr_comment`.
Use [Automations](/web/automations) when review should branch into follow-up
steps, such as:
* review first, then edit only when findings are real
* split review across multiple agents
* keep draft changes separate until a workflow is published
Read next: [GitHub Routing Cookbook](/guides/github-routing-cookbook).
## Triage a new issue [#triage-a-new-issue]
Use [Assignments](/web/assignments) when issue triage is standing
responsibility for one repo.
Use [Triggers](/web/triggers) when `issue_opened` or `issue_comment` should
wake one triage agent for an installation.
Use [Automations](/web/automations) when triage should classify the issue and
then branch into follow-up agents, delays, or edits.
The agent should usually use the `triage` role, not `review`, because the job is
to classify, respond, or decide next steps rather than inspect a code diff.
Read next: [Automation Agent Roles](/web/automations/agent-roles).
## Route a GitHub mention [#route-a-github-mention]
Use [Triggers](/web/triggers) for the smallest mention route:
```text
@mogplex
@mogplex/triage
```
Use [Automations](/web/automations) when a mention should start a workflow
graph instead of waking one agent.
Mention routing depends on exact syntax:
* `@mogplex` is a bare mention
* `@mogplex/` is a targeted mention
* `@mogplex triage` is not a targeted mention
Read next: [GitHub Routing Cookbook](/guides/github-routing-cookbook).
## Start work from Slack [#start-work-from-slack]
Use [Slack](/integrations/slack) when the request naturally starts in a team
channel or DM.
Choose the Slack shape based on context:
* use DMs for conversational help
* use an unlinked channel when Mogplex should answer in Slack without a repo
default
* use a linked channel when `@mogplex` should start repo-agent work for one
repository
If the channel is linked, configure repo-agent enabled state, optional allowed
Slack user IDs, and optional monthly limits before sending broad team traffic
through it.
Read next: [Slack](/integrations/slack).
## Investigate a CI failure [#investigate-a-ci-failure]
Use [Assignments](/web/assignments) when one repo should always use the same CI
failure investigator.
Use [Triggers](/web/triggers) when the CI failure event should wake one agent
from the GitHub App installation.
Use [Automations](/web/automations) when the failure path should branch, such
as review -> condition -> edit.
After the route starts, use [Observability](/web/observability) to find the run,
model calls, tool calls, pressure signals, and errors. Use
[Observability Runbook](/guides/observability-runbook) when you need a full
debug sequence.
## Run Mogplex locally [#run-mogplex-locally]
Use the [Mogplex CLI](/cli) when you want a repo-local cockpit with:
* live timeline events
* approvals and permission gates
* diffs and drawers
* model selection
* MCP and memory context
* token and cost visibility
Install it from [CLI Installation](/cli/installation), then run:
```bash
mogplex
```
Use [Slash Commands](/cli/guides/slash-commands) once the cockpit is open.
## Run Mogplex from CI or scripts [#run-mogplex-from-ci-or-scripts]
Use [Headless Runs](/cli/automation/headless-runs) when a script, CI job, or
dashboard should start a run without opening the interactive cockpit.
Typical sequence:
1. get a repo ID from the CLI or API
2. start a run with `mogplex run --repo ...`
3. tail events with `mogplex runs events --follow`
4. inspect the final status with `mogplex runs get `
Use [CI Integration](/cli/automation/ci-integration) for a GitHub Actions shape.
## Create reusable agent behavior [#create-reusable-agent-behavior]
Use [Agents](/web/agents) when the reusable behavior should be shared across
repos or routing surfaces.
Create or fork an agent when you need durable:
* name and description
* category
* model choice
* system prompt
* mention slug
Use [Skills, Rules, and Context](/web/agents/skills-rules-context) when the
agent needs reusable procedures, shared instructions, or background context.
Read next: [Agent Authoring](/configure-and-extend/agent-authoring).
## Launch or inspect sandbox-backed work [#launch-or-inspect-sandbox-backed-work]
Start with [Projects](/web/spaces) when the repo is the unit of work.
Use [Vercel](/integrations/vercel) when sandbox or preview behavior depends on
repository linkage, project metadata, or environment synchronization.
Use [Sandboxes](/web/sandboxes) when you need to inspect live, pending, pinned,
or stale sandbox state.
Read next: [Sandbox Setup Checklist](/guides/sandbox-setup-checklist).
## Debug a route that did not fire [#debug-a-route-that-did-not-fire]
Check in this order:
1. [Settings](/web/settings) for GitHub identity and account state
2. [Installations](/web/installations) for GitHub App coverage
3. [Projects](/web/spaces) for repo import state
4. the route owner: [Triggers](/web/triggers), [Assignments](/web/assignments),
or [Automations](/web/automations)
5. [Observability](/web/observability), but only after a run actually exists
If the repo is only visible through OAuth, hosted GitHub routing will not be
healthy yet. Fix App coverage first.
## Use the hosted API [#use-the-hosted-api]
Use the [API Reference](/web/api) when another system needs to list repos,
start runs, inspect run events, read model metadata, or fetch runtime state.
Use [API Authentication](/web/api/authentication) before wiring clients. Use
[API Errors](/web/api/errors) when you need response shape and status behavior.
Use [API Quickstart](/web/api/quickstart) when you want the shortest complete
token-to-run path.
## Quick map [#quick-map]
| Job | Start here |
| ------------------------------- | ------------------------------------------------------------ |
| First credible setup | [Quickstart](/quickstart) |
| One event wakes one agent | [Triggers](/web/triggers) |
| One repo owns standing work | [Assignments](/web/assignments) |
| One event starts a graph | [Automations](/web/automations) |
| Local repo work | [Mogplex CLI](/cli) |
| Scripted or CI work | [Headless Runs](/cli/automation/headless-runs) |
| Missing model | [Available Models](/web/models) |
| Model or cost policy | [Model Selection and Cost](/guides/model-selection-and-cost) |
| Sandbox launch setup | [Sandbox Setup Checklist](/guides/sandbox-setup-checklist) |
| Routing or coverage problem | [GitHub App Coverage](/web/guides/github-app-coverage) |
| Slack-started repo work | [Slack](/integrations/slack) |
| Failed, stuck, or expensive run | [Observability Runbook](/guides/observability-runbook) |
# GitHub Routing Cookbook (/guides/github-routing-cookbook)
Use this cookbook when the job begins in GitHub and you need the right Mogplex
route.
For the full decision model, read [Routing](/capabilities/routing) and
[Choose the Right Routing Surface](/web/guides/choose-routing-surface).
## Recipe map [#recipe-map]
| Job | Best first surface |
| ---------------------------------- | ----------------------------------------------------------- |
| Someone comments `@mogplex` | Trigger or Automation with mention start |
| Someone comments `@mogplex/` | Trigger or Automation with matching entry agent slug |
| Every PR needs review | Assignment when repo-owned, Trigger when installation-owned |
| Review should optionally fix code | Automation |
| New issues need triage | Assignment for one repo, Trigger for one installation |
| CI failures need investigation | Assignment or Automation |
| Scheduled maintenance | Assignment with cron or cron refactor type |
| CI should start Mogplex directly | Headless run or v1 API |
## Bare mention route [#bare-mention-route]
Use a bare mention route when users should be able to write:
```text
@mogplex can you summarize the state of this PR?
```
Choose:
* [Triggers](/web/triggers) when one mention should wake one agent
* [Automations](/web/automations) when the mention should start a workflow
graph
The route must be marked as the default mention target for the installation.
Only one default target should own the expected behavior for a given
installation.
## Targeted mention route [#targeted-mention-route]
Use targeted mentions when one repo or org has multiple durable agents:
```text
@mogplex/triage classify this issue and suggest labels.
@mogplex/review inspect this diff for correctness issues.
```
Rules:
* the slash is required
* the text after `/` must match the entry agent slug
* `@mogplex triage` is not targeted routing
* targeted mentions are resolved from GitHub comments, not issue or PR titles
Keep slugs short and job-shaped. Good slugs are easier to remember and easier
to debug in routing rows.
## PR review [#pr-review]
Use [Assignments](/web/assignments) when one repo should always have the same
review behavior.
Use [Triggers](/web/triggers) when the rule belongs to one GitHub App
installation and one event should wake one agent.
Use [Automations](/web/automations) when review should branch:
```text
pr_opened -> review -> condition -> edit or end
```
In automations, use the `review` role for the code-inspection node. Use a
separate `edit` node when the graph should apply changes after the review
result.
## Issue triage [#issue-triage]
Use [Assignments](/web/assignments) when issue triage is standing work for one
repo.
Use [Triggers](/web/triggers) when `issue_opened` or `issue_comment` should
wake one triage agent at the installation level.
Use [Automations](/web/automations) when triage should classify and then branch
into follow-up work.
The first agent is usually `triage`, not `review`, because the job is to read
the thread and decide next steps.
## CI failure response [#ci-failure-response]
For one repo, start with a CI failure assignment.
For one direct event-to-agent rule, use a CI failure trigger.
For a guarded repair flow, use an automation:
```text
ci_failure -> review -> condition -> edit -> publish or end
```
After the route starts, read the route row first for pending, suppressed,
deferred, failed, or pressure state. Then use [Observability](/web/observability)
for model calls, tool calls, sandbox linkage, errors, tokens, and cost.
## Scheduled work [#scheduled-work]
Use [Assignments](/web/assignments) when recurring work belongs to one repo.
Good examples:
* weekly dependency hygiene
* stale issue review
* recurring documentation check
* scheduled refactor investigation
Use a normal cron assignment when the job is operational. Use cron refactor
when the expected work is code-oriented refactoring.
## CI or script starts work directly [#ci-or-script-starts-work-directly]
Use [Headless Runs](/platform/headless-runs), [CI Integration](/cli/automation/ci-integration),
or [API Quickstart](/web/api/quickstart) when GitHub Actions or another system
should start a run directly.
That path is best when the external system already knows:
* repo id
* prompt
* branch intent
* root directory
* timeout or cancellation policy
If the source event is already a GitHub webhook Mogplex supports, a Trigger,
Assignment, or Automation is usually easier to operate than custom CI glue.
## Debugging order [#debugging-order]
When routing does not fire:
1. confirm GitHub App coverage in [Installations](/web/installations)
2. confirm the repo is imported in [Projects](/web/spaces)
3. confirm the route is enabled or published
4. confirm the event type matches the GitHub event that actually happened
5. for mentions, confirm bare vs targeted syntax
6. inspect the route row for pressure, suppression, deferral, or failure
7. move to [Observability](/web/observability) only after a run exists
## Read next [#read-next]
# How to Work With Mogplex (/guides/how-to-work-with-mogplex)
Good Mogplex requests are operationally specific. They name the target, the
desired outcome, the limits, and the proof you expect back.
This matters because the same request can travel through different surfaces:
the CLI composer, a GitHub mention, a Trigger, an Assignment, an Automation, or
a headless run.
## Give the agent a real job [#give-the-agent-a-real-job]
Start with the outcome, not the implementation detail:
```text
Find why the checkout flow fails after billing redirect. Reproduce the failing
path first, then patch the smallest code path that owns the redirect.
```
That is stronger than:
```text
Fix checkout.
```
The useful version tells Mogplex what to inspect, what order to follow, and what
kind of fix is acceptable.
## Include the operating boundaries [#include-the-operating-boundaries]
Add boundaries when they matter:
* whether code edits are allowed
* whether the agent should only diagnose
* whether tests, lint, typecheck, or build should run
* whether the agent should open a PR
* whether the route should stay on the current branch or create a new one
* whether a GitHub reply should be posted or only local changes should be made
Examples:
```text
Diagnose only. Do not edit code. Find why the trigger did not start for this
repo and report the exact missing state.
```
```text
Fix the failing PR check on this branch. Run lint and typecheck before pushing.
Do not change unrelated files.
```
## Name the source of truth [#name-the-source-of-truth]
Mogplex works best when the request says where truth lives.
Good sources of truth include:
* a GitHub PR, issue, or review thread
* a failing CI job
* a local command output
* a route in the web app
* a CLI panel or slash command
* an API endpoint
* a design or screenshot
Example:
```text
Use the latest unresolved PR review comments as scope. Fix only the true
correctness issues and leave style-only suggestions alone.
```
## Use exact mention syntax [#use-exact-mention-syntax]
GitHub mention routing is exact:
```text
@mogplex
@mogplex/triage
@mogplex/frontend-review
```
Use a bare `@mogplex` when the default mention route should decide what to do.
Use `@mogplex/` when you want a specific agent route.
This is not the same as:
```text
@mogplex triage this
```
That is still a bare mention with text after it, not a targeted route.
Read next: [GitHub Mention Routing](/web/guides/github-mention-routing).
## Choose request shape by surface [#choose-request-shape-by-surface]
### CLI [#cli]
Use the CLI for repo-local work where you want to supervise approvals, diffs,
model choice, cost, and timeline events.
```text
/run reproduce the failing activation flow, identify the owning route, patch it,
then run the focused test.
```
Use slash commands when the task is about cockpit state:
* `/model` for model choice
* `/permissions` for permission mode
* `/diff` for patch inspection
* `/cost` for token and cost detail
* `/export` for a portable run artifact
Read next: [Slash Commands](/cli/guides/slash-commands).
### Trigger [#trigger]
Use a short request when the event already contains most of the context.
```text
@mogplex/ci-fixer investigate this failure and propose the smallest fix.
```
If the agent should mutate code, say that explicitly. If it should only report,
say that explicitly.
### Assignment [#assignment]
Assignments should encode stable repo responsibility, so prompts should describe
the durable operating rule.
```text
For this repo, review opened PRs for correctness regressions, missing tests,
and security-sensitive changes. Do not comment on formatting-only issues.
```
When the work changes often, prefer a one-off Trigger or Automation instead of
overloading the assignment.
### Automation [#automation]
Automations should separate decisions from mutations.
A good workflow request names the entry event, the role of each agent, and the
condition for moving to the next step:
```text
On PR opened, review for correctness issues. If real issues are found, branch to
an edit agent that patches them and opens a follow-up PR. Otherwise end after
the review summary.
```
Read next: [Automation Agent Roles](/web/automations/agent-roles).
### Headless run [#headless-run]
For `mogplex run`, put the whole job in the prompt and make the terminal
success condition clear:
```bash
mogplex run --repo "$REPO_ID" --create-branch \
"Run the focused failing test, patch the root cause, rerun the focused test,
and summarize the changed files."
```
Read next: [Headless Runs](/cli/automation/headless-runs).
## Ask for evidence [#ask-for-evidence]
A good request says what proof should come back:
* command output
* screenshot
* test name and result
* route or file path inspected
* PR number
* run ID
* API status code
* observed model or token state
Example:
```text
After the fix, tell me the exact command you ran and whether it passed.
```
## Keep reusable knowledge out of one-off prompts [#keep-reusable-knowledge-out-of-one-off-prompts]
If an instruction should apply repeatedly, put it in the right reusable layer:
* [Agents](/web/agents) for durable agent identity, prompt, slug, and model
* [Repo Instructions](/configure-and-extend/repo-instructions) for local repo
conventions, commands, and verification rules
* [Custom Slash Commands](/configure-and-extend/custom-slash-commands) for
reusable CLI prompt templates
* [Skills, Rules, and Context](/web/agents/skills-rules-context) for shared
procedures, policy, and background knowledge
* [Assignments](/web/assignments) for repo-owned standing work
* [Automations](/web/automations) for repeatable workflow graphs
One-off prompts are best for the current run. Durable behavior belongs in the
product surface that owns it.
## Useful request templates [#useful-request-templates]
### Diagnose only [#diagnose-only]
```text
Diagnose only. Do not edit code. Reproduce the reported behavior, identify the
owning code path or configuration state, and brief me with confirmed findings.
```
### Patch and verify [#patch-and-verify]
```text
Patch the smallest code path that owns this behavior. Run the focused check
first, then the relevant lint/type/build check. Summarize changed files and
validation.
```
### Review [#review]
```text
Review this PR for correctness bugs, regressions, missing tests, and risky
edge cases. Put findings first with file and line references. Keep style-only
comments out unless they hide a real defect.
```
### Route a GitHub mention [#route-a-github-mention]
```text
@mogplex/triage classify this issue, identify the likely owner, and suggest the
next concrete step. Do not edit code.
```
### Create a repeatable workflow [#create-a-repeatable-workflow]
```text
Build an automation for PR-opened events: review first, branch to an edit agent
only when there are confirmed issues, then stop after a summary if no edit is
needed.
```
## Read next [#read-next]
# Guides (/guides)
Guides are task-oriented walkthroughs. Use them when the right product area is
known, but the sequence still matters.
# Model Selection and Cost (/guides/model-selection-and-cost)
Use this guide when the question is not "which models exist?" but "which model
should this work use, and how do I keep spend understandable?"
The live catalog lives in [Available Models](/web/models). This page is the
operating model for choosing and reviewing those models across Mogplex.
## Start from the job [#start-from-the-job]
Pick the smallest capable model for the workflow, then move up only when the
work proves it needs more reasoning, context, or tool reliability.
| Job | Good starting point | Watch for |
| ------------------------ | ------------------------------------------------- | ------------------------------------------------------------- |
| Fast issue triage | Lower-cost model with solid instruction following | Long threads, many linked files, or ambiguous product context |
| PR review | Strong code reasoning model | Large diffs, multi-package changes, security-sensitive code |
| Code edit | Strong implementation model | Repo size, test setup, tool-call reliability, branch handling |
| Documentation pass | Balanced writing and code-reading model | Claims that need source verification in sibling repos |
| CI failure investigation | Strong reasoning model with good tool use | Flaky tests, remote logs, environment-specific failures |
| Recurring automation | Predictable low-to-mid cost model | Repeated failures that create hidden retries or requeues |
Model choice is a routing policy decision. A cheap model on a high-volume route
can still spend more than an expensive model on a narrow route.
## Know the control points [#know-the-control-points]
Model configuration appears in several places:
| Surface | What it controls |
| ------------------------------------------ | ------------------------------------------------------------------- |
| [Settings -> Models](/web/models) | Enabled models, disabled models, and the default model for new work |
| [Plans & Billing](/plans-and-billing) | Account-level managed access for hosted model usage |
| [Agents](/web/agents) | The default model for that reusable agent |
| [Automations](/web/automations) | Node-level model overrides inside one workflow draft |
| [Repo settings](/web/spaces) | Repo-specific exclusions from the globally enabled model set |
| [CLI Model Picker](/cli/reference/drawers) | Active model for the local cockpit run |
| [API Models](/web/api/models) | Catalog, enabled state, and CLI-formatted model export |
The account default affects new work. It does not rewrite every saved agent,
automation node, assignment, or repo rule.
## Recommended workflow [#recommended-workflow]
1. Open [Available Models](/web/models) and make sure the account has at least
one enabled model.
2. Confirm the plan includes the level of model usage the workflow needs.
3. Set a default model that is safe for ordinary new work.
4. Give specialized agents explicit models when the job needs it.
5. Use automation node overrides only when one node differs from the base
agent on purpose.
6. Add repo-specific exclusions when a codebase should not use a model family,
provider, or cost profile.
7. Review [Observability](/web/observability) and [Cost & Usage](/cli/reference/cost-and-usage)
after real runs, not just after setup.
## When to override the default [#when-to-override-the-default]
Override the account default when:
* the agent has a durable job such as security review, CI repair, or release
work
* the automation node has a different role than the reusable agent usually has
* a repo has policy or cost restrictions
* the route is high-volume and needs a lower-cost baseline
* the CLI run is a one-off task where the operator knows the tradeoff
Do not override just because a model is newer. The route should explain why the
model is needed.
## Cost visibility [#cost-visibility]
Use these surfaces together:
* [Observability](/web/observability) for hosted runs, automation runs,
pressure, tokens, estimated cost, model calls, and tool calls
* [Cost & Usage](/cli/reference/cost-and-usage) for local cockpit totals,
threshold warnings, and per-run breakdowns
* [API Models](/web/api/models) for pricing metadata when present in the model
catalog
If spend jumps, do not start by changing every model. First identify the route,
agent, repo, and surface that generated the calls.
## Safe cost controls [#safe-cost-controls]
Use these controls before broad disabling:
| Control | Use it when |
| -------------------------------- | ------------------------------------------------------------ |
| Disable one model | The model should not be selectable for new work |
| Repo exclusion | One repo should not use a model that remains valid elsewhere |
| Agent model change | One durable worker should use a different model |
| Automation node override | One step in one graph needs a different model |
| CLI `/model` | A human operator wants to switch the current local run |
| Approval rule for `change_model` | Model changes should require operator consent |
Avoid using a global disable as a substitute for repo policy. It can break
unrelated agents that are correctly using the model.
## Hidden or stale model references [#hidden-or-stale-model-references]
Long-lived agents and automations can still reference older model ids.
When you edit those definitions:
1. open the model field
2. move the definition to a visible enabled model
3. save the agent or automation draft
4. run one small test before changing a high-volume route
If the CLI is signed in but does not show the expected model list, confirm the
web account has enabled models and that the CLI is using account-backed login.
## Read next [#read-next]
# Observability Runbook (/guides/observability-runbook)
Use this runbook after something has tried to run.
If no work was emitted at all, start with the owning route surface instead:
[GitHub](/integrations/github), [Triggers](/web/triggers),
[Assignments](/web/assignments), [Automations](/web/automations),
[Slack](/integrations/slack), [CLI](/platform/cli), or the
[API Quickstart](/web/api/quickstart).
## First Question [#first-question]
Ask one question before opening every page:
**Did Mogplex create a run, call, or sandbox record?**
| Answer | Start here |
| ------ | ---------------------------------------------------------------------------------------------------------- |
| No | Source surface: GitHub coverage, Slack channel link, Trigger, Assignment, Automation, CLI, or API request. |
| Yes | [Observability](/web/observability), then the linked run, call, or sandbox row. |
| Unsure | Check Observability by time window, then search by repo or source surface. |
Observability is strongest after work exists. It is not the best proof that a
GitHub webhook, Slack mention, or API request was routed correctly before a run
was created.
## Gather The Minimum Facts [#gather-the-minimum-facts]
Before changing configuration, capture:
* source surface: CLI, API, Slack, GitHub mention, Trigger, Assignment, or
Automation
* repo owner/name and Mogplex repo ID
* run ID or call ID if one exists
* sandbox ID if a preview/runtime exists
* model and provider
* first error message
* whether the status is pending, streaming, success, failed, or cancelled
Those facts usually identify the owning layer.
## Read The Summary Cards First [#read-the-summary-cards-first]
Open [Observability](/web/observability) and read the cards before opening row
details.
Use them to decide whether the problem is:
* broad pressure, such as stale pending work or start failures
* isolated runtime failure
* high token or cost usage
* sandbox-related
* local CLI activity rather than hosted automation
Then open the exact Activity row.
## Expand The Activity Row [#expand-the-activity-row]
The expanded row is the source of truth for runtime debugging.
Check in this order:
1. surface badge
2. repo and source metadata
3. model and call type
4. error string
5. event timeline
6. tool calls
7. sandbox metadata and preview URL
8. raw metadata only if the higher-level fields are not enough
Do not edit the agent prompt until you know whether the failure came from the
model, a tool, connection state, sandbox state, or routing setup.
## No Run Appears [#no-run-appears]
If no row appears in Observability:
* GitHub event: check [Installations](/web/installations) and
[GitHub Routing Cookbook](/guides/github-routing-cookbook).
* Slack mention: check [Slack](/integrations/slack) channel links, user
mapping, repo-agent enabled state, and monthly/user limits.
* Trigger or Assignment: check enabled state, repo scope, and selected agent.
* Automation: check published version, active state, start event, and entry
agent role.
* API request: check token scope, idempotency key, response code, and repo ID.
* CLI run: check CLI auth, local config, and whether the failure is local-only.
The fastest fix is usually on the source surface, not in Observability.
## Pending Or Stuck Work [#pending-or-stuck-work]
When a run exists but stays pending:
1. Check summary cards for stale pending work or start failures.
2. Open the run row and inspect the first event.
3. Check sandbox allocation state if the run needs a sandbox.
4. Check managed model access if the run never reaches a model call.
5. Check whether the source surface is repeatedly re-enqueuing the same work.
If the run came from the public API, use
`GET /api/v1/mogplex/runs/{runId}` and
`GET /api/v1/mogplex/runs/{runId}/events` to compare API state with the UI.
## Model Or Access Failure [#model-or-access-failure]
For model access errors:
1. Confirm the model exists in [Available Models](/web/models).
2. Confirm the user or team plan includes access to hosted model usage.
3. Check whether the agent, repo, or route excludes the model.
4. Compare token and cost fields to see whether the call reached execution.
Use [Model Selection and Cost](/guides/model-selection-and-cost) when the model
is available but the default, route, or cost policy is unclear.
## Tool Or Connection Failure [#tool-or-connection-failure]
For external tool failures:
1. Open [Settings](/web/settings#connections) and test the connection.
2. Confirm the connection is enabled.
3. Confirm the repo did not exclude a global connection.
4. Confirm project-scoped connections are attached to the repo that ran.
5. Open the Activity row and inspect the tool-call payload and error.
If the failure involves MCP sync into the CLI, check
[MCP Servers API](/web/api/mcp-servers) and local CLI auth separately.
## Sandbox Or Preview Failure [#sandbox-or-preview-failure]
For sandbox-backed failures:
1. Open the linked sandbox from the Activity row when available.
2. Check root directory, install command, dev command, dev port, and env source.
3. Check managed sandbox access and optional Vercel project metadata.
4. Check branch and preview URL.
5. Stop, restart, or delete only after capturing the first failure event.
Use [Sandbox Setup Checklist](/guides/sandbox-setup-checklist) for launch
configuration, and [Projects and Sandboxes](/platform/projects-and-sandboxes)
for the platform model.
## Cost Or Token Spike [#cost-or-token-spike]
For unexpectedly high usage:
1. Filter Activity by surface.
2. Sort or scan for high-token calls.
3. Compare model, run source, tool calls, and sandbox linkage.
4. Check whether an automation loop, Slack route, or API retry generated extra
starts.
5. Move the policy decision back to the source: model choice, routing volume,
repo exclusion, or monthly limit.
Use [Model Selection and Cost](/guides/model-selection-and-cost) when the fix is
policy, not a one-off failed run.
## Escalation Packet [#escalation-packet]
When handing the issue to another person, include:
* run ID or call ID
* source surface and exact trigger text or API response
* repo owner/name and repo ID
* first event and first error
* model id
* sandbox ID or preview URL if applicable
* what changed immediately before the failure
Leave out raw credentials, `mog_...` tokens, Slack link URLs, decrypted MCP
config, and full `.env` files. See
[Security and Data Handling](/reference/security-and-data-handling) for the
safe-sharing checklist.
## Read Next [#read-next]
# Sandbox Setup Checklist (/guides/sandbox-setup-checklist)
Use this checklist when a workspace, preview, or cloud run depends on a Mogplex
sandbox.
Most sandbox failures are configuration failures. Confirm the repo launch
contract before changing agents, prompts, routes, or models.
## Checklist [#checklist]
| Check | Why it matters |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| GitHub App coverage | Hosted work needs installation-backed repo access, not only OAuth visibility |
| Repo import state | Mogplex needs a repo record before it can launch workspace or API runs |
| Root directory | Monorepos need the exact app/package path instead of repo root |
| Install command | Dependency setup should match the package manager and workspace path |
| Dev command | The preview process must start the actual app or service |
| Dev port | The preview router needs the port the app listens on |
| Environment variables | Missing secrets usually look like app boot or preview health failures |
| Managed sandbox access | Workspace launch depends on the account plan including sandbox access |
| Vercel project metadata | Optional env sync and preview settings can depend on linked Vercel project state |
| Branch intent | Decide whether the sandbox should work on default branch, an existing branch, or a new branch |
| Timeout and idle behavior | Long-running previews need realistic timeout expectations |
## First repo setup [#first-repo-setup]
1. Confirm [Installations](/web/installations) shows the GitHub owner and repo.
2. Open [Projects](/web/spaces) and sync repos if needed.
3. Set `root_directory` for monorepos.
4. Set install command, dev command, and dev port.
5. Add required env vars or secrets.
6. Confirm managed sandbox access, and only then check optional Vercel-linked
preview metadata if the repo uses it.
7. Launch one workspace manually before adding triggers or automations.
If the manual workspace launch fails, fix the project settings before debugging
routing.
## Branch choices [#branch-choices]
Pick branch behavior intentionally:
| Pattern | Use it when |
| ------------------ | ----------------------------------------------------------- |
| Default branch | You only need to inspect or test without preserving edits |
| Existing branch | The work should continue an already-open change |
| New working branch | The agent should isolate edits and push a branch for review |
API runs can set `baseBranch`, `workingBranch`, and `createBranch`. The web app
offers the same concept through the sandbox launch flow.
## Monorepos [#monorepos]
For monorepos, write the launch contract down explicitly:
* repo full name
* root directory
* package manager
* install command
* dev command
* dev port
* env var source
* expected preview path
Do not assume the repo root is correct just because dependency install starts.
The app can still boot from the wrong workspace or expose the wrong port.
## Broken preview path [#broken-preview-path]
When a preview is unhealthy:
1. open [Sandboxes](/web/sandboxes)
2. find the sandbox by repo and branch
3. check whether it is creating, running, paused, stopped, stale, or failed
4. open health/runtime detail from the sandbox row when available
5. use [Observability](/web/observability) only after a run or runtime event
exists
If no sandbox exists, return to [Projects](/web/spaces), repo settings, and
GitHub coverage.
## What not to debug first [#what-not-to-debug-first]
Avoid changing these until the sandbox launch contract is known-good:
* agent prompt
* model
* automation graph
* trigger event
* assignment type
* CLI auth
Those can affect work quality, but they do not fix a repo that cannot install,
boot, expose the right port, or load secrets.
## API and CLI checks [#api-and-cli-checks]
Use the API to list sandboxes for one repo:
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/sandboxes?repo_id=&limit=20"
```
Use the CLI when you want a table or JSON from a terminal:
```bash
mogplex sandboxes list
mogplex sandboxes list --json
mogplex sandboxes list --repo --status running
```
Sandbox lifecycle actions should be done in the web UI until the v1 lifecycle
API is exposed.
## Read next [#read-next]
# Troubleshooting (/guides/troubleshooting)
Use this guide when something did not work and you need the shortest path to
the owning surface.
Start by deciding whether the failure happened before work started or after
work started.
## First split [#first-split]
| Symptom | Most likely layer |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Repo is missing or stale | account sync or Projects |
| Repo is visible but GitHub events do not fire | GitHub App coverage |
| Mention does not route | agent slug, default mention route, or route enabled state |
| Slack mention replies but does not start repo work | Slack channel link, user mapping, repo-agent enabled state, or workspace limits |
| Route exists but no run appears | route source, coverage, enabled state, or published automation |
| Run appears but fails | runtime, model, tool, connection, sandbox, or prompt |
| Preview is unhealthy | repo settings, managed sandbox access, optional Vercel metadata, sandbox state, or dev command |
| Model is missing from a picker | model catalog, plan access, default model, or repo exclusion |
| CLI signs in but state looks wrong | CLI auth, account state, local config, or synced hosted state |
## Debug order [#debug-order]
1. Check [Settings](/web/settings) for identity, account access, model
defaults, CLI tokens, connections, and GitHub account state.
2. Check [Installations](/web/installations) for GitHub App coverage.
3. Check [Projects](/web/spaces) for repo visibility, repo settings, and
sandbox launch state.
4. Check [Agents](/web/agents) for slug, model, prompt, category, skills,
rules, and context.
5. Check the route source: [Triggers](/web/triggers),
[Assignments](/web/assignments), or [Automations](/web/automations).
6. Check [Slack](/integrations/slack) when Slack is the source surface.
7. Check [Observability](/web/observability) only after a run exists.
8. Check [Sandboxes](/web/sandboxes) when a preview/runtime is involved.
## Repo is visible but events do not fire [#repo-is-visible-but-events-do-not-fire]
Visibility and triggerability are different.
1. Open [Installations](/web/installations).
2. Confirm the repo owner is covered by the Mogplex GitHub App.
3. Confirm the route is on the same installation or repo that owns the event.
4. Confirm the route is enabled, or the automation is published.
5. If work starts, continue into [Observability](/web/observability).
Do not tune the agent prompt until App-backed coverage is healthy.
## Mention routing fails [#mention-routing-fails]
Check the exact comment text first.
```text
@mogplex
@mogplex/triage
```
Rules:
* bare `@mogplex` needs a default mention route
* targeted `@mogplex/` needs an agent slug match
* `@mogplex triage` is not targeted
* PR or issue comments without `@mogplex` are normal comment events, not
mention events
Read [GitHub Mention Routing](/web/guides/github-mention-routing) for the full
model, or use [GitHub Routing Cookbook](/guides/github-routing-cookbook) for
concrete route recipes.
## Slack mention starts the wrong behavior [#slack-mention-starts-the-wrong-behavior]
Slack and GitHub mentions have different routing models.
For Slack:
* `@mogplex` in a linked channel starts a repo-agent run
* `@mogplex` in an unlinked channel stays conversational
* DMs stay conversational
* thread replies continue an existing Slack-backed conversation
If Slack replies conversationally when you expected repo work:
1. open [Slack](/integrations/slack)
2. confirm the workspace is installed
3. confirm the channel is linked to the target repo
4. confirm repo-agent runs are enabled
5. confirm the Slack user is mapped and allowed
6. check the monthly run limit
7. if a run starts, continue into
[Observability Runbook](/guides/observability-runbook)
## Model is missing [#model-is-missing]
Start with [Available Models](/web/models).
Check:
* whether the model is visible in the live catalog
* whether the model is enabled for the account
* whether the account plan includes access to that model
* whether the agent is pinned to a hidden legacy model
* whether a repo or route excludes the model
* whether the CLI has synced the expected hosted state
Use [API Models](/web/api/models) only when you need the route behavior, not the
user-facing picker explanation.
Use [Model Selection and Cost](/guides/model-selection-and-cost) when the model
exists but the route, agent, repo, or cost policy is unclear.
## CLI state looks wrong [#cli-state-looks-wrong]
Start with [CLI Authentication](/cli/guides/authentication) and
[Configuration and Flags](/cli/guides/configuration-and-flags).
Check:
* the signed-in account shown by the CLI
* local `~/.mogplex` auth and permission state
* environment variables overriding expected config
* whether hosted model defaults or MCP definitions are synced as expected
* repo-local permission rules when tool approvals feel surprising
Use the app [Settings](/web/settings) page to confirm the hosted account state
that the CLI should inherit.
## Sandbox or preview is unhealthy [#sandbox-or-preview-is-unhealthy]
Start from [Projects](/web/spaces) if repo settings may be wrong.
Start from [Sandboxes](/web/sandboxes) if a runtime already exists and you need
to inspect, stop, delete, or open the exact instance.
Check:
* root directory
* install command
* dev command
* dev port
* environment mapping
* managed sandbox access
* optional linked Vercel team and project metadata
* sandbox timeout
* active branch and preview URL
Use [Observability](/web/observability) when you need the linked run, call,
tool, cost, or error trail.
Use [Sandbox Setup Checklist](/guides/sandbox-setup-checklist) when launch
settings are still uncertain.
## API request fails [#api-request-fails]
Start with [API Authentication](/web/api/authentication) and
[API Errors](/web/api/errors).
Check:
* whether the route accepts PAT auth or requires a browser session
* whether the token has `read` or `write` scope
* whether the request expects the v1 run API envelope or a product route shape
* whether idempotency keys are being reused with a different body
* whether the response error code is retryable
Use [Working Requests](/web/api/working-requests) for known-good examples.
Use [API Quickstart](/web/api/quickstart) for the shortest complete path from
token to repo lookup, run start, event inspection, cancellation, and sandbox
listing.
## What to capture before escalating [#what-to-capture-before-escalating]
* repo owner/name and repo ID if available
* GitHub owner coverage state from Installations
* route source: CLI, Trigger, Assignment, Automation, API, or GitHub mention
* Slack workspace and channel link state when Slack started the work
* exact GitHub event or comment text
* agent slug and model
* run ID, sandbox ID, or API response body
* first error message, not only the final retry
* whether Observability has any matching record
## Read next [#read-next]
# GitHub (/integrations/github)
GitHub is the first integration most Mogplex accounts need.
It does two separate jobs:
* identity and repo discovery through GitHub OAuth
* webhook-backed routing through the Mogplex GitHub App
Keep those separate while debugging. A repo can be visible in
[Projects](/web/spaces) and still fail to trigger hosted work if the owner does
not have GitHub App coverage.
## Setup order [#setup-order]
1. Open [Settings](/web/settings) and connect GitHub.
2. Install the Mogplex GitHub App for the user or org that owns the repos.
3. Confirm installation coverage in [Installations](/web/installations).
4. Sync or import repos in [Projects](/web/spaces).
5. Choose the routing surface that matches the work:
[Triggers](/web/triggers), [Assignments](/web/assignments), or
[Automations](/web/automations).
6. Verify the first run in [Observability](/web/observability).
## OAuth vs GitHub App coverage [#oauth-vs-github-app-coverage]
| State | What it unlocks | What it does not unlock yet |
| ------------------------------ | -------------------------------- | ------------------------------------------- |
| GitHub disconnected | Nothing GitHub-backed | Repo import, repo creation, webhook routing |
| OAuth connected | Account identity and repo import | Webhook-backed routing |
| App installed | Repo coverage for GitHub events | Synced repos until import or sync completes |
| App installed and repos synced | Full GitHub-backed setup | N/A |
Use [GitHub App Coverage](/web/guides/github-app-coverage) when a repo is
visible but [Triggers](/web/triggers) or [Automations](/web/automations) cannot
route work into it.
## What GitHub can start [#what-github-can-start]
Mogplex GitHub routing can start work from issue comments, PR comments, PR
review comments, commit comments, repo events, and the specific routing events
exposed by the current trigger or automation surface.
The important choice is scope:
* use [Triggers](/web/triggers) for one GitHub event waking one agent
* use [Assignments](/web/assignments) for durable repo-owned work
* use [Automations](/web/automations) for graph-shaped work with branching,
delays, publishing, or parallel agents
## Mention routing [#mention-routing]
Mogplex recognizes two mention forms in GitHub comments:
* `@mogplex`
* `@mogplex/`
Bare `@mogplex` routes only to the default mention target. Targeted mentions
route by agent slug.
Use [GitHub Mention Routing](/web/guides/github-mention-routing) for the exact
rules, including entry-agent behavior in automations.
## Where to check state [#where-to-check-state]
* [Settings](/web/settings): GitHub connection state and account-level setup
* [Installations](/web/installations): App coverage, repo eligibility, and
synced repo state
* [Projects](/web/spaces): imported repo list, repo settings, and workspace
entry points
* [Observability](/web/observability): run status and failure trail after a
GitHub event starts work
## Common failures [#common-failures]
* **Repo is visible but triggers are empty**: OAuth is connected, but App
coverage is missing for the repo owner.
* **Mention does not wake the expected agent**: the comment may be bare
`@mogplex` when it needed `@mogplex/`, or the wrong route is
marked default.
* **Automation cannot find the expected repo**: check installation coverage and
repo sync before editing the automation.
* **PR review work starts in the wrong shape**: use an Assignment for standing
repo responsibility, not a one-off Trigger.
## Read next [#read-next]
# Integrations (/integrations)
Integrations connect Mogplex to the systems that own source code, identity,
runtime credentials, automation, and external tools.
## Integration order [#integration-order]
Start with GitHub identity, GitHub App coverage, and managed account access
before debugging webhook routing. Add optional Vercel metadata, Slack, MCP
servers, and CI entry points only after the account can see and cover the repo
that should run.
# Slack (/integrations/slack)
Slack lets a team talk to Mogplex without leaving the workspace where the work
was requested.
The integration has two modes:
* **Conversational mode** for DMs and existing Slack threads
* **Repo-agent mode** for linked channels where an `@mogplex` mention starts a
run against a specific repository
Use this page when Slack is installed but the response, repo context, or run
policy is not doing what you expect.
## What Slack Can Do [#what-slack-can-do]
| Slack surface | Behavior |
| ------------------------------------ | --------------------------------------------------------------------------- |
| Direct message | Mogplex replies in Slack and keeps conversation context for that DM thread. |
| Thread reply in a bound conversation | Mogplex continues the existing Slack-backed conversation. |
| `@mogplex` in an unlinked channel | Mogplex replies conversationally, without repo-agent context. |
| `@mogplex` in a linked channel | Mogplex starts a repo-agent run for the linked repo. |
The linked-channel behavior is intentionally different from general chat. Once
a channel is linked to a repo, a real user input after `@mogplex` is treated as
a request to start repository work.
## Setup Order [#setup-order]
1. Open [Settings](/web/settings) and go to Connections.
2. Install Mogplex to Slack, or add another workspace if one already exists.
3. Expand the installed workspace.
4. Link the Slack channel to the Mogplex repo that should own repo-agent runs.
5. Enable repo-agent runs for that workspace.
6. Optionally restrict the Slack user IDs allowed to start repo-agent runs.
7. Optionally set a monthly repo-agent run limit for the workspace.
8. Test from Slack with a real instruction after `@mogplex`.
For private channels, invite the Mogplex Slack app to the channel before trying
to link or route from it.
## Channel Links [#channel-links]
A channel link maps one Slack channel to one Mogplex repo.
When a user posts this in a linked channel:
```text
@mogplex inspect the failing checkout flow and open a minimal fix
```
Mogplex starts a repo-agent run against the linked repo, posts a run link back
to the Slack thread, and exposes a Slack-side cancel control while the run is
active.
Use channel links when the channel has a stable repository meaning, such as:
* one channel per product repo
* one channel per customer-facing service
* one channel for release, CI, or incident follow-up on a single codebase
Do not link a broad discussion channel unless every `@mogplex` request there
should default to the same repo.
## Repo-Agent Controls [#repo-agent-controls]
Each Slack workspace has its own repo-agent controls.
| Control | Use it for |
| ---------------------- | --------------------------------------------------------------------------- |
| Repo agent runs | Disable all Slack-started repo-agent runs without disconnecting Slack chat. |
| Allowed Slack user IDs | Restrict who can start repo-agent runs from the workspace. |
| Monthly limit | Cap how many repo-agent runs Slack can start in that workspace each month. |
These controls apply to Slack-started repo-agent runs. They do not replace
Mogplex account auth, GitHub App coverage, repo import, or model access.
## User Mapping [#user-mapping]
Mogplex needs to know which Mogplex user a Slack user represents before it can
act.
Resolution happens in this order:
1. use an explicit Slack-to-Mogplex link if one exists
2. attempt to match the Slack user's email to a Mogplex profile
3. post an account-link notice if no Mogplex user can be resolved
If Slack posts a link prompt instead of running work, complete that account link
first. Do not debug agent routing until the Slack user is mapped.
## Attachments [#attachments]
Slack image attachments can be passed into the run.
Supported image types are:
* PNG
* JPEG
* WebP
* GIF
Mogplex currently accepts up to four Slack image attachments per request, with a
5 MB ceiling per image. Extra, unsupported, external, or unavailable files are
dropped and reported to the agent as attachment notices.
For repo-agent runs, accepted images are materialized into the sandbox under a
Mogplex-owned ignored path so the agent can inspect them without committing the
files.
## Debug Slack Routing [#debug-slack-routing]
| Symptom | Check |
| ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| Slack install button fails | The app must have Slack OAuth env configured in the deployed Mogplex app. |
| Workspace appears but channels do not | Invite the bot to the channel, then reload the channel list. |
| Mention replies conversationally instead of starting a run | The channel is not linked to a repo, or the event was not an `app_mention`. |
| Repo-agent request is denied | Check repo-agent enabled state, allowed Slack user IDs, and monthly limit. |
| Slack asks the user to link their account | Complete the Slack account link before starting work. |
| Run starts but fails later | Use [Observability](/web/observability) and the run link posted in Slack. |
## Security Notes [#security-notes]
Slack install and webhook paths are guarded separately:
* OAuth install state is signed and nonce-checked.
* Slack webhooks are verified with the Slack signing secret.
* Bot tokens are stored server-side and resolved only when Slack work needs
them.
* Repo-agent runs still depend on the Mogplex user's repo access, model access,
and workspace configuration.
Slack is a convenient entry point, not a bypass around Mogplex ownership and
execution rules.
## Read Next [#read-next]
# Vercel (/integrations/vercel)
Vercel is optional integration metadata for repos that need project-aware
preview settings.
Mogplex-managed billing owns sandbox access. Use the Vercel integration when a
repo needs Vercel-linked project settings for previews, root directories, and
environment sync. Do not use it as an external sandbox account path.
## Where Vercel is configured [#where-vercel-is-configured]
Vercel setup is primarily repo state:
* [Projects](/web/spaces) owns repo-specific Vercel team, project, root
directory, env mapping, install command, dev command, port, and timeout
settings.
* [Sandboxes](/web/sandboxes) shows live and pending runtime state after a
sandbox exists.
* [Observability](/web/observability) shows the call, job, sandbox, model, and
cost trail after work starts.
## Billing model [#billing-model]
Sandbox usage is billed through Mogplex. A linked Vercel project can provide
preview metadata and environment sync, but it is not the billing source for
Mogplex sandboxes.
That means you can configure GitHub coverage, repo import, agents, triggers,
assignments, and automations without asking users to attach their own sandbox
account.
## Repo-linked project settings [#repo-linked-project-settings]
Use [Projects](/web/spaces) when one repo needs Vercel-specific runtime
configuration:
* Vercel team and project mapping
* root directory for monorepos
* install command
* dev command
* dev port
* sandbox timeout override
* environment mapping mode
* manual environment variables in `.env`-style `KEY=value` format
This matters most for monorepos and preview apps where the default repo root is
not the app Mogplex should run.
## Environment sync [#environment-sync]
Repo settings control how sandbox environment variables are assembled.
Use manual repo variables when Mogplex needs values that are not sourced from a
Vercel project. Use Vercel-linked sync when the repo should inherit environment
state from the selected Vercel project, with repo settings acting as the
Mogplex-side control point.
If a preview boots but behaves like the wrong app or misses expected env vars,
check the repo root, env mapping mode, Vercel project mapping, and manual repo
vars together.
## Preview and sandbox troubleshooting [#preview-and-sandbox-troubleshooting]
Start from the surface that owns the failure:
* Repo configuration problem: [Projects](/web/spaces)
* Runtime already exists but looks stuck: [Sandboxes](/web/sandboxes)
* Need the call or job trail behind the runtime: [Observability](/web/observability)
* Account lacks managed sandbox access: [Plans & Billing](/plans-and-billing)
Common failure modes:
* **Sandbox launch says access is unavailable**: the account plan may not
include managed sandbox access yet.
* **Preview opens the wrong app**: set the repo root directory, install
command, dev command, and dev port explicitly.
* **Env values are missing**: inspect env mapping mode, linked Vercel project
state, and manual repo variables in Projects.
* **Runtime exists but workspace open lands wrong**: open the workspace from
[Sandboxes](/web/sandboxes) so it binds to the exact sandbox instance.
## Read next [#read-next]
# Glossary (/reference/glossary)
Use this page when a Mogplex page names a product object and you need the
short version before reading the full guide or reference page.
## Account state [#account-state]
Shared state attached to the signed-in Mogplex account.
Account state includes GitHub identity, GitHub App coverage, Slack installs,
access tokens, managed model access, shared connections, and MCP
definitions. Start with [Settings](/web/settings) when account state looks
wrong.
## Agent [#agent]
A reusable worker definition.
Agents have a name, description, category, model choice, prompt, and sometimes
a mention slug. Agents can be built-in presets, owned custom agents, or forks of
presets you have customized.
Read next: [Agents](/web/agents).
## Agent slug [#agent-slug]
The durable handle used for targeted GitHub mention routing.
Example:
```text
@mogplex/triage
```
The slug is not the same as the display name. If a route depends on targeted
mentions, use the slug in the GitHub comment.
Read next: [Roster and Slugs](/web/agents/roster-and-slugs).
## Assignment [#assignment]
A repo-owned standing work rule.
Assignments bind one repo, one agent, and one assignment type, such as PR
review, issue triage, CI failure, cron, or cron refactor. Use Assignments when
the repo is the durable unit of responsibility.
Read next: [Assignments](/web/assignments).
## Automation [#automation]
A workflow graph for GitHub-triggered work.
Automations start from one GitHub event, then move through nodes such as agent
steps, conditions, parallel splits, joins, and delays. Draft edits do not
become live routing until the automation is published.
Read next: [Automations](/web/automations).
## Connection [#connection]
A configured external service or credential path that an agent or hosted run can
use.
Connection behavior can depend on account state, repo state, and route-specific
overrides. If a run cannot call an external service, start with
[Settings](/web/settings), [Connections and MCP](/configure-and-extend/connections-and-mcp),
and [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides).
## Custom slash command [#custom-slash-command]
A markdown prompt template that becomes a named command in the CLI composer.
Commands can be project-scoped under `.agents/commands`, user-scoped under the
Mogplex home commands directory, or built in. Project commands override user
commands, and user commands override builtins.
Read next: [Custom Slash Commands](/configure-and-extend/custom-slash-commands).
## GitHub App coverage [#github-app-coverage]
The state that lets Mogplex receive webhook-backed GitHub events for a user or
organization.
OAuth visibility can make repos visible in the app, but GitHub App coverage is
what makes hosted routing healthy for Triggers and Automations. If a repo is
visible but events do not start work, check App coverage first.
Read next: [GitHub App Coverage](/web/guides/github-app-coverage).
## Headless run [#headless-run]
A run started from scripts, CI, or shell commands instead of the interactive
CLI cockpit.
Headless runs use `mogplex run` and `mogplex runs ...` commands and wrap the
hosted runs API.
Read next: [Headless Runs](/cli/automation/headless-runs).
## Installation [#installation]
A GitHub App installation for a GitHub user or organization.
Installations are the coverage layer for webhook-backed work. Triggers and
Automations are installation-scoped. Assignments are repo-scoped but still
depend on the repo being imported and covered correctly.
Read next: [Installations](/web/installations).
## MCP [#mcp]
Model Context Protocol configuration for connecting agents and clients to
external tools.
Mogplex currently documents MCP through the extension path and API surface:
inbound configuration, configured MCP server definitions, and the planned
outbound Mogplex MCP server path.
Read next: [Connections and MCP](/configure-and-extend/connections-and-mcp),
[MCP](/extend/mcp-server), and [MCP Servers API](/web/api/mcp-servers).
## Model catalog [#model-catalog]
The model list available to an account and exposed to agents, model pickers,
the CLI, and API surfaces.
Use [Available Models](/web/models) for user-facing model availability. Use
[API Models](/web/api/models) for API behavior.
## Observability [#observability]
The runtime inspection surface for runs, model calls, tool calls, sandbox
activity, token usage, estimated cost, pressure, and errors.
Use Observability after a route or run actually starts. If no run exists, debug
the source surface first.
Read next: [Observability](/web/observability).
## Project [#project]
The web-app surface where imported repos become workspaces for hosted work.
Projects are where repo setup, sync state, sandbox launch, and hosted work
entrypoints come together. The docs also link this area as
[Projects](/web/spaces), matching the current route.
Read next: [Projects](/web/spaces).
## Repo visibility [#repo-visibility]
Whether Mogplex can see a repo through account sync.
Visibility is not the same as triggerability. A repo can be visible through
OAuth but still unable to start hosted GitHub-event work until the owning user
or organization has GitHub App coverage.
Read next: [GitHub](/integrations/github).
## Repo instructions [#repo-instructions]
Durable local guidance stored in `AGENTS.md`, `AGENTS.override.md`, and
occasionally `agent.json`.
Use repo instructions for project purpose, commands, conventions, and
verification rules that should shape many runs. Keep one-off task detail in the
current prompt.
Read next: [Repo Instructions](/configure-and-extend/repo-instructions).
## Run [#run]
One execution of Mogplex work.
Runs can start from the CLI, headless commands, the hosted API, Triggers,
Assignments, Automations, Slack, or GitHub events. Use run IDs when inspecting
status, tailing events, exporting local state, or asking someone else to debug
a failure.
Read next: [API Runs](/web/api/runs) and [CLI Export](/cli/reference/export).
## Sandbox [#sandbox]
An isolated runtime or preview workspace associated with hosted work.
Use Sandboxes to inspect live and pending preview runtimes, pinned workspaces,
and stale sandbox cleanup paths. Use Vercel docs when sandbox behavior depends
on repo-linked project metadata or environment sync.
Read next: [Sandboxes](/web/sandboxes) and [Vercel](/integrations/vercel).
## Slack channel link [#slack-channel-link]
A mapping from one Slack channel to one Mogplex repo.
When a channel is linked, a real instruction after `@mogplex` starts a
repo-agent run for that repo. Unlinked channels and DMs stay conversational.
Read next: [Slack](/integrations/slack).
## Skill [#skill]
A reusable capability or workflow package that helps shape agent behavior.
In Mogplex docs, skills appear in two related contexts:
* product-side reusable behavior under [Skills, Rules, and Context](/web/agents/skills-rules-context)
* local agent-host skills under [CLI Skills](/cli/skills)
## Trigger [#trigger]
The lightest hosted routing surface.
Triggers bind one GitHub App installation, one event type, and one agent. Use
Triggers when the route is simply one event to one agent.
Read next: [Triggers](/web/triggers).
## Triggerability [#triggerability]
Whether a visible repo can actually start hosted GitHub-event work.
Triggerability requires the right GitHub App coverage. If a repo appears in
Projects but Triggers or Automations do not fire, debug triggerability before
changing the agent.
Read next: [Coverage and Triggerability](/web/installations/coverage-and-triggerability).
## Working request [#working-request]
The API and runtime shape used to represent work that should be started,
tracked, or inspected.
Use the hosted API pages when another system needs to create or inspect work
programmatically.
Read next: [Working Requests API](/web/api/working-requests).
# Reference (/reference)
Reference pages are for exact behavior: route families, request and response
shape, command behavior, cockpit surfaces, keybindings, drawers, cost reporting,
and export formats.
# Security and Data Handling (/reference/security-and-data-handling)
This page is the practical trust reference for Mogplex.
Use it when you need to know which credential is involved, where sensitive
state lives, what appears in logs or API responses, and what to capture safely
when debugging.
## The Main Trust Boundaries [#the-main-trust-boundaries]
Mogplex crosses several systems:
* GitHub OAuth and the Mogplex GitHub App for identity, repo discovery, and
webhook-backed routing
* managed sandbox access for preview runtimes
* managed model access for hosted execution
* Slack OAuth and webhooks for Slack conversations and repo-agent starts
* REST and MCP connections for tools agents can call
* personal access tokens for CLI, scripts, and the public v1 API
* sandboxes for executing repo work
When debugging, identify which boundary failed before rotating credentials or
changing agent prompts.
## Authentication And Tokens [#authentication-and-tokens]
Mogplex personal access tokens use the `mog_...` prefix. The token value is
shown once when created and is stored server-side as a SHA-256 hash.
Current public API scopes are:
| Scope | Allows |
| ------- | -------------------------------------------------------------------------- |
| `read` | List and detail endpoints such as repos, runs, sandboxes, and MCP servers. |
| `write` | Mutations such as starting or cancelling runs. |
API tokens can be revoked from Settings. Expired, revoked, malformed, or
unknown tokens resolve as unauthenticated. Valid tokens are also rate-limited
per key before route handlers proceed.
Use [API Authentication](/web/api/authentication) for request examples and
scope behavior.
## Managed Model Access [#managed-model-access]
Hosted model execution is billed and authorized through Mogplex account access.
Users do not need external model credentials for hosted runs. If a model cannot
be used, debug the account plan, model catalog, and entitlement state instead
of rotating local shell credentials.
## Connections And MCP Secrets [#connections-and-mcp-secrets]
Connections are external tools Mogplex can call.
Connection credentials are encrypted server-side before storage. MCP server
secrets and provider-backed connection tokens are resolved only when the
connection or MCP sync path needs them.
Two details matter operationally:
* A healthy connection in Settings can still be excluded from a specific repo.
* `GET /api/v1/mogplex/mcp/servers` returns resolved MCP config for a PAT
caller, which can include decrypted headers or env values.
Treat MCP server responses like a `.env` file. Do not paste them into issues,
chat logs, CI output, or screenshots.
Read [Connection Scope and Overrides](/web/guides/connection-scope-and-overrides)
and [MCP Servers API](/web/api/mcp-servers) for the exact behavior.
## Webhooks [#webhooks]
GitHub and Slack use separate webhook verification paths.
| Source | Verification |
| ------ | ------------------------------------------------------------ |
| GitHub | HMAC signature against the configured GitHub webhook secret. |
| Slack | Slack request signature plus timestamp/body checks. |
Slack install state is also signed, nonce-checked, and time-limited during the
OAuth callback. Slack account-link URLs are bearer links, so treat the raw link
as sensitive until it expires or is consumed.
## Event And Audit Data [#event-and-audit-data]
Mogplex stores runtime events so users can inspect what happened after a run
starts.
Run-event payloads are sanitized before returning through the public events
API. Sensitive keys are redacted, long strings are truncated, and deeply nested
or oversized payloads are capped so event data is useful without becoming a raw
secret dump.
Team audit payloads also redact fields whose names look like prompts, tokens,
API keys, credentials, passwords, or secrets.
Even with those controls, support requests should include identifiers and the
first error string, not raw credentials, full env dumps, or full private prompts.
## Sandboxes [#sandboxes]
Sandboxes run repository work in an isolated runtime, but they are still allowed
to interact with the repo, configured environment, connected tools, and model
provider selected for the run.
Before starting sandbox work, confirm:
* the repo and branch are correct
* root directory, install command, dev command, and port are correct
* the environment source is intentional
* managed sandbox access is available for the account
* optional linked Vercel project metadata is intentional when used
* Slack or GitHub routing is starting work under the user you intend
Use [Sandbox Setup Checklist](/guides/sandbox-setup-checklist) before treating a
sandbox failure as a model or agent bug.
## What To Share Safely [#what-to-share-safely]
Good support artifacts:
* repo owner/name and Mogplex repo ID
* run ID, sandbox ID, automation ID, or API request ID
* GitHub App installation owner and coverage state
* Slack workspace name and channel link state
* first error message and timestamp
* model id and provider name
* whether the request came from CLI, API, Slack, GitHub, Trigger, Assignment,
or Automation
Avoid sharing:
* `mog_...` tokens
* Slack account-link URLs
* decrypted MCP server config
* `.env` files
* OAuth tokens
* full private prompts or proprietary code excerpts unless needed and approved
## Rotation Checklist [#rotation-checklist]
Rotate or revoke the smallest credential that matches the risk:
* Revoke a Mogplex PAT when API or CLI access is exposed.
* Reconnect GitHub or Slack when OAuth state is wrong or the workspace owner
changes.
* Recreate a connection when an external REST or MCP credential was exposed.
* Stop or delete a sandbox when runtime state may contain sensitive files.
Then re-test the exact owning surface before changing agent prompts or routing.
## Read Next [#read-next]
# Mogplex App (/platform/app)
The Mogplex app is the hosted control plane.
Use it when the question is about shared account state, GitHub coverage, repo
visibility, reusable agents, hosted routing, sandbox state, models, settings,
or runtime inspection.
The app is not just the browser version of the CLI. It owns the shared state
that other surfaces consume.
## What the app owns [#what-the-app-owns]
| Area | What it controls |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| [Settings](/web/settings) | GitHub identity, App coverage, managed access, access tokens, connections, model defaults, and preferences |
| [Projects](/web/spaces) | Repo import, workspace launch, repo settings, sandbox startup, monorepo entries, assignments, and cron setup |
| [Agents](/web/agents) | Reusable agents, preset forks, categories, slugs, model choice, skills, rules, and context |
| [Triggers](/web/triggers) | One GitHub event routed directly to one agent |
| [Assignments](/web/assignments) | Repo-owned standing work such as review, triage, CI failure response, and scheduled jobs |
| [Automations](/web/automations) | Multi-step GitHub-triggered workflows with branches, delays, parallel work, drafts, and publishing |
| [Sandboxes](/web/sandboxes) | Running and pending preview runtimes across repos |
| [Observability](/web/observability) | Run health, pressure, model calls, tool calls, tokens, sandbox linkage, and cost |
## Start here when [#start-here-when]
* a repo is missing, duplicated, hidden, or not triggerable
* a GitHub event does not start work
* an agent slug, model, prompt, rule, skill, or context library needs to be
changed centrally
* a sandbox preview is starting, failing, stale, or attached to the wrong repo
* you need to understand what actually ran and what it cost
## Healthy first setup [#healthy-first-setup]
For a new account or new repo, use the app in this order:
1. Connect GitHub and confirm managed account access in [Settings](/web/settings).
2. Confirm App-backed repo coverage in [Installations](/web/installations).
3. Sync and open the target repo in [Projects](/web/spaces).
4. Check reusable behavior in [Agents](/web/agents).
5. Choose the smallest routing surface that fits the work.
6. Inspect the first run in [Observability](/web/observability).
That order prevents the common failure mode where a team starts debugging
automation logic before the repo is actually covered by the GitHub App.
## App vs CLI [#app-vs-cli]
Use the app for shared setup and hosted state.
Use the [CLI](/platform/cli) when you are sitting in a repo and need live
control over a run: timeline, agents, approvals, diffs, MCP, memory, model
choice, cost, and export.
The two surfaces are intentionally connected. For example, the CLI can inherit
account-backed model defaults and remote MCP definitions from hosted state.
## Read next [#read-next]
# Mogplex CLI (/platform/cli)
The Mogplex CLI is the terminal cockpit for active repo work.
Run `mogplex` when you want to start, steer, inspect, approve, pause, resume,
kill, or export an agent run from the terminal.
## What the CLI is best at [#what-the-cli-is-best-at]
* watching a run end to end without leaving the repo
* approving or rejecting gated tool calls as they happen
* opening diffs, MCP detail, memory, model choice, cost, and export drawers
* attaching to an in-flight run that started somewhere else
* using slash commands for operator control
The CLI is built around live structured events. It is not only a command
launcher and it is not only a log viewer.
## Main entrypoints [#main-entrypoints]
| Need | Start here |
| ------------------------------------------ | ---------------------------------------- |
| Install the CLI | [Installation](/cli/installation) |
| First local run | [CLI Quickstart](/cli/quickstart) |
| Understand the cockpit | [CLI Overview](/cli) |
| Learn the control model | [CLI Concepts](/cli/concepts) |
| Type commands in the composer | [Slash Commands](/cli/commands) |
| Use panels, drawers, keys, cost, or export | [CLI Reference](/cli/reference) |
| Run without the interactive UI | [Headless Runs](/platform/headless-runs) |
## Where local state lives [#where-local-state-lives]
The CLI reads local Mogplex state from `~/.mogplex`, including auth,
permissions, project overrides, and redacted logs.
Project-level behavior can also come from repo-local configuration and
permission rules. Use the CLI pages when you need exact behavior for approval
gates, permission modes, attach mode, transports, drawers, or keybindings.
## CLI vs headless runs [#cli-vs-headless-runs]
Use the interactive CLI when a human operator should supervise the run.
Use [Headless Runs](/platform/headless-runs) when a CI job, dashboard, script,
or other automation should start a run and consume events without opening the
terminal UI.
Both paths still rely on the same hosted run concepts and API-backed state.
## App relationship [#app-relationship]
The app owns shared account setup and routing. The CLI owns local supervision.
That means a healthy CLI experience usually depends on:
* [Settings](/web/settings) for auth, models, CLI tokens, and connections
* [Available Models](/web/models) for model availability and defaults
* [Projects](/web/spaces) for imported repos and hosted repo state
* [Observability](/web/observability) for cross-surface run inspection after
work starts
## Read next [#read-next]
# Headless Runs (/platform/headless-runs)
Headless runs are for non-interactive execution.
Use this surface when another system should start Mogplex work, tail the event
stream, and make a decision from the final status.
## Good fits [#good-fits]
* GitHub Actions or another CI system starts a fix or investigation run
* an internal dashboard launches a repo task
* a scheduled script starts maintenance work
* a tool starts a run and streams events into its own logs
* an operator wants repeatable JSON output instead of the TUI
If a human should actively supervise tool approvals, diffs, or model changes,
use the [interactive CLI](/platform/cli) instead.
## Core lifecycle [#core-lifecycle]
The headless path mirrors the hosted run lifecycle:
1. start a run with a repo and task
2. capture the run ID
3. tail run events, optionally as JSON
4. inspect the final run status
5. cancel or retry only when the status supports it
The CLI wraps the v1 runs API and adds CI-friendly behavior such as JSON output,
idempotency keys, event following, and exit-code-mapped errors.
## Typical command shape [#typical-command-shape]
```bash
export MOGPLEX_API_KEY="mog_..."
RUN_ID=$(
mogplex run --repo "$MOGPLEX_REPO" --create-branch --json \
"Investigate the failing test and propose the smallest fix." \
| jq -r '.runId'
)
mogplex runs events "$RUN_ID" --follow --timeout 900
mogplex runs get "$RUN_ID" --json
```
For the exact flags, output fields, idempotency behavior, and event format, use
[CLI Automation: Headless Runs](/cli/automation/headless-runs).
## Requirements [#requirements]
* a Mogplex API key with the right scope
* a repo ID from Mogplex, not only an owner/name string
* a clear task prompt suitable for unattended execution
* timeout and final-status handling in the calling script
Use read-only tokens for dashboards that should inspect runs but never start or
cancel them.
## Where to inspect results [#where-to-inspect-results]
Use [Observability](/web/observability) after the run starts if you need:
* model calls and token usage
* tool calls and errors
* sandbox linkage
* pressure or queue signals
* cost and duration
Use the API pages when another system needs to consume the same run data:
[Runs API](/web/api/runs), [API Errors](/web/api/errors), and
[Working Requests](/web/api/working-requests).
## Read next [#read-next]
# Hosted API (/platform/hosted-api)
The hosted API is the control-plane surface behind the Mogplex app and parts of
the CLI.
Use it when another system needs to inspect or drive Mogplex state directly:
repos, runs, models, MCP servers, sandboxes, settings, and runtime activity.
## Use the API when [#use-the-api-when]
* a CI job or internal tool needs to start or inspect runs
* a dashboard needs repo, run, model, or observability state
* the CLI needs hosted account state
* you are debugging current route behavior in the product
* an adjacent service should behave like the app
Prefer the app when a human is configuring account setup, GitHub coverage,
agents, routing, or sandboxes interactively.
## Product-first route model [#product-first-route-model]
The hosted API follows product surfaces. It is not documented as a frozen
long-term public REST platform yet.
That means you should read it from the product outward:
1. identify the surface you are trying to drive
2. find the route family behind that surface
3. confirm the auth mode and response envelope
4. document the routes your own integration depends on
## Route families [#route-families]
| Family | Examples |
| ------------------------- | -------------------------------------------------------------------- |
| Identity and settings | `/api/auth/*`, `/api/settings`, `/api/models` |
| Projects and GitHub state | `/api/repos`, `/api/workspaces`, `/api/github/*` |
| Reusable behavior | `/api/agents`, `/api/skills`, `/api/rules`, `/api/mcp-servers` |
| Routing | `/api/triggers`, `/api/assignments`, `/api/flows` |
| Runtime | `/api/chat`, `/api/commands`, `/api/sandbox`, `/api/observability/*` |
| v1 public run surface | `/api/v1/mogplex/*` |
For the concrete map, use [Route Families](/web/api/route-families).
## Auth model [#auth-model]
The same hosted surface can be reached through browser session auth, personal
access tokens, and internal test auth depending on the route.
Start with:
* [API Authentication](/web/api/authentication) for PATs, scopes, idempotency,
and browser auth behavior
* [API Errors](/web/api/errors) for envelope shape and retry guidance
* [Working Requests](/web/api/working-requests) for copyable examples
## Good first calls [#good-first-calls]
* `GET /api/auth/user` to confirm setup state
* `GET /api/settings` to inspect shared defaults
* `GET /api/models` to inspect model availability
* `GET /api/github/installations` to confirm GitHub App coverage
* `GET /api/v1/mogplex/mcp/servers` to export CLI-ready MCP definitions
* `GET /api/observability/stats` to inspect runtime health and usage
## Read next [#read-next]
# How Mogplex Fits Together (/platform/how-mogplex-fits-together)
Mogplex is easier to debug once the platform objects have clear ownership.
Most product questions reduce to this chain:
```text
account -> GitHub installation -> repo -> agent -> route -> run -> observability
\
sandbox
```
Each object answers a different question.
## Core objects [#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 |
| Sandbox | Runtime and preview environment for repo work | previews, workspace sessions, branches, ports, env, or stale runtimes are involved |
| Observability record | Captured runtime details | you need calls, tools, errors, tokens, cost, pressure, or sandbox linkage |
## Ownership map [#ownership-map]
| Product area | Primary ownership |
| ---------------------------------------- | ------------------------------------------------------------------------------------- |
| [Settings](/web/settings) | account state |
| [Installations](/web/installations) | GitHub App coverage |
| [Slack](/integrations/slack) | Slack workspace install, channel-to-repo links, and Slack-started repo-agent controls |
| [Projects](/web/spaces) | repos, workspace sessions, repo settings, sandbox launch |
| [Agents](/web/agents) | reusable behavior and mention slugs |
| [Triggers](/web/triggers) | installation-scoped event-to-agent routes |
| [Assignments](/web/assignments) | repo-scoped standing work |
| [Automations](/web/automations) | workflow graph routing |
| [CLI](/platform/cli) | local run supervision |
| [Headless Runs](/platform/headless-runs) | script and CI execution |
| [Sandboxes](/web/sandboxes) | cross-repo runtime operations |
| [Observability](/web/observability) | runtime inspection |
## The important splits [#the-important-splits]
### Visibility vs triggerability [#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](/web/guides/github-app-coverage) before editing routes.
### Agent definition vs route binding [#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 state vs sandbox state [#run-state-vs-sandbox-state]
A run is the unit of work.
A sandbox is the runtime environment the work may use.
Some failures are run failures. Some are preview/runtime failures. If a run is
linked to a sandbox, inspect both [Observability](/web/observability) and
[Sandboxes](/web/sandboxes) before changing prompts or routing.
### Interactive vs unattended execution [#interactive-vs-unattended-execution]
Use the [CLI](/platform/cli) when a human operator should supervise the work.
Use [Headless Runs](/platform/headless-runs) or the [Hosted API](/platform/hosted-api)
when another system should start work unattended.
## A route from setup to runtime [#a-route-from-setup-to-runtime]
1. Account state makes the user able to use Mogplex.
2. GitHub App coverage makes the repo owner eligible for webhook-backed work.
3. Projects imports the repo and stores repo runtime settings.
4. Agents define reusable behavior.
5. Triggers, Assignments, or Automations bind that behavior to events or repos.
6. Slack channel links can also bind a Slack channel to one repo.
7. A run starts.
8. A sandbox may launch or attach.
9. Observability captures the runtime story.
If the chain breaks, debug the earliest missing object first.
## Read next [#read-next]
# Platform (/platform)
Mogplex has several product surfaces, but they share one platform: account
state, GitHub coverage, reusable agents, model access, run history, sandbox
state, and API-backed execution.
Start here when you need to understand where work should happen.
## How the platform fits together [#how-the-platform-fits-together]
* The app owns shared account setup, GitHub App coverage, routing, hosted
state, and inspection.
* The CLI owns repo-local supervision: agents, timeline, approvals, diffs,
model choice, cost, export, and attach mode.
* Headless runs use the same platform API when the job starts from CI, scripts,
dashboards, or scheduled automation.
* Projects and sandboxes connect repo identity to execution state.
For the object model behind those surfaces, read
[How Mogplex Fits Together](/platform/how-mogplex-fits-together).
## Read next [#read-next]
# Projects and Sandboxes (/platform/projects-and-sandboxes)
Projects and Sandboxes are the repo execution layer of the app.
Use [Projects](/web/spaces) when you are choosing or configuring a repo. Use
[Sandboxes](/web/sandboxes) when the runtime itself is the thing you need to
inspect or control.
## Mental model [#mental-model]
| Term | Meaning |
| ----------------- | --------------------------------------------------------- |
| Repo | The imported GitHub repository Mogplex knows about |
| Project | The app grouping layer shown as Projects at `/spaces` |
| Workspace session | The live repo session you open from the app |
| Sandbox | The runtime and preview environment attached to repo work |
This split matters because repo visibility, workspace launch, and sandbox
health are related but not identical.
## Use Projects when [#use-projects-when]
* syncing repos or checking whether the right repo is visible
* searching and organizing repo cards
* opening a workspace
* configuring root directory, install command, dev command, dev port, env
mapping, timeout, secrets, or snapshot state
* creating repo-bound assignments or cron-backed work
* choosing a sub-project inside a monorepo
Projects is where sandbox launch usually begins because the repo card has the
repo settings needed to start the right runtime.
## Use Sandboxes when [#use-sandboxes-when]
* you need one cross-repo list of live and pending previews
* a runtime is stuck creating, installing, unhealthy, stale, or attached to the
wrong branch
* you need to open a workspace pinned to a specific sandbox instance
* you need manual Stop or Delete controls
* you want to jump from a runtime to health or observability
Sandboxes is the operational runtime list. It answers:
**Which preview is actually alive right now?**
## Common paths [#common-paths]
### First repo setup [#first-repo-setup]
1. Confirm GitHub coverage in [Installations](/web/installations).
2. Sync and find the repo in [Projects](/web/spaces).
3. Set root directory, dev command, preview port, optional Vercel metadata, or env
mapping if needed.
4. Open the workspace or start preview from the repo card.
### Broken preview [#broken-preview]
1. Find the runtime in [Sandboxes](/web/sandboxes).
2. Open Health if the runtime exists but the preview is unhealthy.
3. Open [Observability](/web/observability) from sandbox context when you need
run, call, cost, or tool detail.
4. Stop or delete stale runtimes only when the current state supports it.
### Monorepo work [#monorepo-work]
Use Projects to create sub-project entries or set `root_directory`,
`dev_command`, and `dev_port` explicitly. Do not rely on one repo root when the
actual app lives under a package or app directory.
## Billing and Vercel relationship [#billing-and-vercel-relationship]
Sandbox access is billed through Mogplex. Optional linked Vercel project
metadata can still matter for preview env sync or project-specific settings. If
sandbox launch fails after repo setup, confirm [Plans & Billing](/plans-and-billing)
and [Vercel](/integrations/vercel) before editing routing or agent behavior.
## Read next [#read-next]
# Assignments (/web/assignments)
Assignments are the repo-to-agent routing layer for repeatable work.
Instead of listening to a GitHub App installation broadly like
[Triggers](/web/triggers), Assignments bind a specific repo to a specific agent
and a specific work type. That makes the repo, not the installation, the
durable unit of routing.
Think of an assignment as a standing contract:
**for this repo, run this kind of work with this agent.**
## Use Assignments when [#use-assignments-when]
* one repo should always have the same review or triage behavior
* the repo itself is the source of truth for what should run
* you want standing work without building a workflow graph
* you need recurring cron-driven work tied to one repo
If the source of truth is a GitHub event across an installation, use
[Triggers](/web/triggers). If the routing needs branching, joins, delays, or
multiple steps, use [Automations](/web/automations).
## Why Assignments exists [#why-assignments-exists]
Assignments is the middle ground between lightweight triggers and full
workflow graphs.
It keeps durable repo-owned work close to the repo itself:
* standing PR review
* push review
* issue triage
* CI failure response
* scheduled maintenance or refactor work
## Supported assignment types [#supported-assignment-types]
Current assignment types are:
* **PR Review** (`pr_review`)
* **Push Review** (`push_review`)
* **Issue Triage** (`issue_triage`)
* **CI Failure** (`ci_failure`)
* **Cron** (`cron`)
* **Cron Refactor** (`cron_refactor`)
The Projects surface can create some of these directly from a repo card, which
is usually the fastest path when you already know the repo that owns the work.
## Creation model [#creation-model]
Every assignment is a three-part mapping:
1. choose the repo
2. choose the agent
3. choose the assignment type
If you choose a built-in preset agent, Mogplex resolves it to an owned agent
before saving the assignment. It reuses your existing fork of that preset when
one already exists, or creates a fork in your account automatically.
That behavior is why assignment creation can appear to “materialize” a custom
agent even though you started from a preset.
## What the page shows after creation [#what-the-page-shows-after-creation]
Each assignment row is both a routing rule and a small operational console.
It can show:
* the repo and agent pair
* assignment type
* last run status and timestamp
* failed, running, pending, suppressed, and deferred counts
* the latest error string
* the latest pressure reason when start was intentionally held
* inline **Repair**, **Cancel**, and **Requeue** controls when the latest job
supports them
That means Assignments is not just where you define repeatable work. It is also
the first place to see whether that work is healthy.
## Recommended workflow [#recommended-workflow]
1. Create the assignment from the target repo and agent.
2. Let the first run happen naturally from its source event or schedule.
3. Read the assignment row first for status, pressure, and last error.
4. Use **Repair**, **Cancel**, or **Requeue** only when the current job state
supports it.
5. Move into [Observability](/web/observability) when you need call-level,
tool-level, or sandbox-linked detail.
## What healthy assignment operations look like [#what-healthy-assignment-operations-look-like]
* the repo and assignment type still match the work you actually want
* the agent is durable and owned, not an accidental temporary experiment
* the row shows recent status clearly enough that you do not need to open deeper
runtime views for every check
* repairs or requeues are the exception, not the default operating mode
## Good fits [#good-fits]
* a standing PR review agent for one repo
* a repo-specific CI failure investigator
* an issue triage agent for a busy service repo
* a scheduled maintenance or refactor job
* a push review agent for a sensitive branch or codebase
## Common mistakes [#common-mistakes]
* using Assignments for cross-installation event routing
* using Assignments when the logic really needs branching or multi-step flow
control
* treating the assignment row as the full debugging surface instead of the
summary surface
## Read the signals correctly [#read-the-signals-correctly]
* **Failed** usually means the latest job did start and ended badly.
* **Pending** means work is queued but not running yet.
* **Suppressed** means Mogplex intentionally declined to start that work.
* **Deferred** means the system delayed start because of pressure or fleet
controls.
* **Pressure: ...** means you should inspect the reason before retrying
blindly.
If you need to understand model choice, tool calls, sandbox linkage, or cost,
continue into [Observability](/web/observability).
# Overview (/web)
The web app is the shared source of truth for Mogplex account state, GitHub
coverage, reusable agents, hosted routing, and runtime inspection.
If the question is about account setup, GitHub eligibility, reusable hosted
behavior, or why something ran the way it did, the answer usually starts here.
## What the web app actually owns [#what-the-web-app-actually-owns]
* **Projects** lives at `/spaces`. It is where repository import, project
organization, sandbox launch, and workspace opening happen.
* **Sandboxes** lives at `/spaces/sandboxes`. It is the cross-repo runtime
view for running, pending, and stale preview environments.
* **Agents** lives under `/agents/*` and manages the reusable agent roster plus
shared skills, rules, and context.
* **Automations** at `/automations` is the canvas builder for multi-step
GitHub-triggered workflows.
* **Triggers** at `/triggers` is the lighter-weight event-to-agent router for
direct GitHub webhook handling.
* **Assignments** at `/assignments` binds repos to agents for repeatable review,
cron, and triage work.
* **Observability** tracks runs, pressure, failures, model calls, tool usage,
and sandbox-linked activity.
* **Settings** manages GitHub identity, App coverage, connections, access
tokens, models, preferences, billing access, and synced MCP definitions.
* **Available Models** explains the live model catalog, enabled-state rules,
default-model behavior, plan access, CLI sync, and repo-level exclusions.
## The clean mental model [#the-clean-mental-model]
The web app is not just “the browser version of the CLI.”
It owns three different jobs:
* **setup**: identity, GitHub coverage, connections, models, and repo sync
* **routing**: deciding what should run from GitHub events, repo-owned rules,
or workflow graphs
* **inspection**: checking runs, failures, tool calls, cost, and sandbox health
That framing helps you choose the right page faster:
* use [Settings](/web/settings) and [Installations](/web/installations) when
Mogplex cannot yet do the work
* use [Available Models](/web/models) when a picker, agent, flow, or CLI run
cannot use the model you expect
* use [Projects](/web/spaces), [Triggers](/web/triggers),
[Assignments](/web/assignments), or [Automations](/web/automations) when you
are deciding what should run
* use [Observability](/web/observability) and [Sandboxes](/web/sandboxes) after
work has queued or started
## Start in this order [#start-in-this-order]
For a new account or a new repo, the most reliable path through the product is:
1. [Settings](/web/settings) to connect GitHub and confirm your account can use
the product.
2. [Installations](/web/installations) to verify GitHub App coverage for the
correct user or org.
3. [Projects](/web/spaces) to sync repos, organize them, and open a workspace.
4. [Agents](/web/agents) to create or fork the agents you actually want to run.
5. [Triggers](/web/triggers), [Assignments](/web/assignments), or
[Automations](/web/automations) depending on how much routing logic you
need.
That sequence matters because most apparent “routing bugs” are really setup
bugs: missing App coverage, missing repo sync, or missing shared account state.
## Choose the smallest routing surface that fits the job [#choose-the-smallest-routing-surface-that-fits-the-job]
* Use **Triggers** when the rule is simply `one GitHub event -> one agent`.
* Use **Assignments** when the repo is the durable unit of routing and you want
standing work such as PR review, issue triage, CI failure response, or cron.
* Use **Automations** when you need multiple steps, branching, delays,
publishable drafts, or explicit mention-entry workflows.
If the choice is not obvious yet, read
[Choose the Right Routing Surface](/web/guides/choose-routing-surface).
## Web app vs CLI [#web-app-vs-cli]
The clean split is usually:
* do shared account setup, GitHub coverage, and routing in the web app
* do repo-local execution in the CLI
* come back to the web app for observability, repair actions, and shared
hosted state
This matters because Mogplex intentionally reuses some hosted state in the CLI,
including account-backed model defaults and remote MCP definitions.
## What a healthy setup feels like [#what-a-healthy-setup-feels-like]
Once the web app side is set up correctly:
* the correct repos appear in [Projects](/web/spaces)
* the correct owner shows real GitHub App coverage in
[Installations](/web/installations)
* the agents you expect are available for routing
* Triggers or Automations offer real installations instead of looking empty
* [Observability](/web/observability) can tell you what actually ran
## Legacy route notes [#legacy-route-notes]
Several older dashboard routes still exist, but they now forward to the current
surfaces:
* [`/flows`](/web/flows) redirects to `/automations`
* [`/library`](/web/library) redirects to agent libraries or model settings,
depending on tab
* [`/primitives`](/web/primitives) redirects to the agent library surfaces
The product language still says **Projects** even though the route is
`/spaces`. The docs use the current UI label and call out the route where it
matters.
For the full redirect map, use [Legacy Routes](/web/guides/legacy-routes).
## Common “where do I fix this?” questions [#common-where-do-i-fix-this-questions]
* **Why is Triggers empty?** Usually because GitHub OAuth is connected but the
Mogplex GitHub App is not installed for the owner that holds the repo. Check
[Installations](/web/installations).
* **Why can I see repos but not launch the kind of work I want?** Repo sync and
webhook coverage are separate concerns. Projects can show synced repos before
they are fully triggerable.
* **Where do I set up models and external tools?** Use
[Settings](/web/settings) for account access and connections, and
[Available Models](/web/models) for model availability, defaults, and enabled
state. Agent behavior belongs in [Agents](/web/agents).
* **Where do I manually stop or inspect previews across repos?** Use
[Sandboxes](/web/sandboxes).
* **Where do I start for mention-driven workflows?** Use
[Triggers](/web/triggers) for a direct mention route, or
[Automations](/web/automations) if the mention should fan into a workflow.
# Library (/web/library)
The legacy `/library` route still exists in the app, but it no longer owns one
standalone surface.
It now forwards to one of these current destinations:
* `/agents/skills` by default
* `/agents/rules` when the old link asked for the rules tab
* `/agents/context` when the old link asked for the context tab
* `/settings#models` when the old link asked for the models tab
Use those pages for the current product behavior.
## Current mapping [#current-mapping]
If you are cleaning up old bookmarks or internal links, this is the mapping the
app uses today:
* `/library` -> skills
* `/library?tab=rules` -> rules
* `/library?tab=context` -> context
* `/library?tab=models` -> models in Settings
## Why the route still exists [#why-the-route-still-exists]
Older navigation and saved links used `/library` as the entrypoint for shared
skills, rules, context, and models.
Mogplex now splits that content between the [Agents](/web/agents) area and
[Settings](/web/settings), but the redirect remains in place so existing links
do not break.
## What the old Library concept became [#what-the-old-library-concept-became]
The old Library idea has been split by responsibility.
### Skills [#skills]
Use [Agents](/web/agents) -> Skills for reusable behavior packs.
The current skills surface includes:
* a **skills.sh** registry browser
* a **Vercel Docs** importer for turning docs pages into local runbook-style
skills
* a **Local** skills area for the skills you already have installed or created
Local skills are currently grouped by type:
* runbook
* tool
* prompt
* workflow
### Rules [#rules]
Use [Agents](/web/agents) -> Rules for global rule files that constrain or
guide agent behavior.
This surface is file-oriented:
* create markdown rule files
* open and edit existing ones
* delete stale ones
Think of Rules as account-level instructions you want multiple agents to share.
### Context [#context]
Use [Agents](/web/agents) -> Context for memory and reusable context records.
The current context surface is organized into four lanes:
* **Session** for the active working set
* **Semantic** for durable facts and preferences
* **Episodic** for timeline events and milestones
* **Procedural** for workflows and runbooks
You can search, add, delete, compact, and checkpoint memories there, and the
surface scopes to the current repo or workspace session when that context is
available.
### Models [#models]
Use [Settings](/web/settings) -> Models for account-level model availability
and defaults.
That is where you:
* enable or disable models
* choose the default model for new agents and new automation nodes
That default is only the starting point. Existing agent overrides and
automation-node overrides still win over the account default.
## How to think about it now [#how-to-think-about-it-now]
The old Library concept has been split by job:
* use [Agents](/web/agents) for reusable behavior such as skills, rules, and
shared context
* use [Settings](/web/settings) for account-level model enablement and default
selection
That split matches how the product works now: agent-building artifacts live
with the roster, while model selection lives with the rest of your hosted
configuration.
## Rule of thumb [#rule-of-thumb]
If the thing you are editing changes what agents know or how they behave, it
belongs under [Agents](/web/agents).
If the thing you are editing changes which models are available or what new
agents default to, it belongs under [Settings](/web/settings).
# Available Models (/web/models)
The live model catalog lives in the web app. This page mirrors a recent
snapshot for browsing, then explains how to read the catalog and where model
choices take effect.
Model availability, pricing, context length, provider reachability,
recommendations, and enabled state can change by account, team, plan,
entitlement, and sync state. Treat the snapshot below as a reference; the web
app is the source of truth.
## Catalog snapshot [#catalog-snapshot]
Search by id, provider, or name. Filter by provider or capability — selecting
multiple capabilities requires all of them. The snapshot is regenerated from
the Supabase `ai_models` table by `pnpm gen:models`.
## Where to see models [#where-to-see-models]
Open [Settings](/web/settings) and use the **Models** section.
That section is the product-facing model catalog. It shows the models Mogplex
can currently present to the signed-in account, including:
* provider
* model name and model id
* context length when known
* input and output pricing when known
* capabilities when present in the catalog
* availability
* enabled or disabled state
* recommendation badges when Mogplex has current recommendation metadata
* the current default model
The API-shaped reference for this same data lives at
[API → Models](/web/api/models).
## What the Models section controls [#what-the-models-section-controls]
The Models section controls account-level model preference state.
| Control | What it changes |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Enabled / Disabled | Whether a model is selectable for new work. Disabled models are removed from normal pickers and from the CLI-oriented model list. |
| Set default | Which enabled model new agents and new automation nodes use unless another model is chosen. |
| Search and filters | How you inspect the catalog by provider, model id, state, pricing metadata, and sort order. |
Existing agents, automation nodes, and repo settings can still carry explicit
model choices. A default is the starting point for new work, not a global
rewrite of every saved configuration.
## How model access is determined [#how-model-access-is-determined]
For a model to be useful, two things must line up:
1. the model must be visible and available in the catalog
2. the account or team must have plan-backed access to use it
Mogplex-hosted model access is managed by the account plan. Settings can show
which models are enabled for the account, but users do not need external model
credentials for hosted runs.
If no usable model is available, check the account plan or entitlement state
before debugging agents, flows, or CLI login.
## Enabled models vs hidden models [#enabled-models-vs-hidden-models]
Most users only need the enabled/disabled split:
* **Enabled** models appear in normal model pickers.
* **Disabled** models stay in the account catalog but are not offered for new
work.
Mogplex also has a hidden-model state for legacy catalog hygiene. Hidden models
do not appear as normal choices, but saved agents or flows can still show legacy
warnings if they reference an old hidden model id. Move those saved definitions
to a visible enabled model when you edit them.
## How the CLI uses models [#how-the-cli-uses-models]
When you sign in to the CLI with Mogplex account login, the cockpit can reuse
the hosted model catalog.
In the CLI:
* the Header shows the active model for the current run
* `/model` opens the Model Picker drawer
* the picker uses the synced enabled model list when account-backed state is
available
* switching models can be gated by the `change_model` approval rule
See [CLI → Quickstart](/cli/quickstart) and
[Reference → Drawers](/cli/reference/drawers).
## How agents and automations use models [#how-agents-and-automations-use-models]
[Agents](/web/agents) choose from enabled models. When you create a new custom
agent or fork a preset, Mogplex starts from the current default model unless you
choose another enabled model.
[Automations](/web/automations) follow the same principle for new agent nodes.
The default model is a convenience for new nodes; node-level overrides still
belong to the automation draft.
If an agent or automation node says its model is unavailable, check the Models
section before editing prompts or routing logic.
## Repo-level exclusions [#repo-level-exclusions]
Repos can have their own model surface in repo settings.
Models enabled globally can be excluded for one repo or space without disabling
them everywhere else. Use this when one codebase should not use a specific
provider, model family, or cost profile.
That scope split is:
* global enabled state in **Settings → Models**
* repo-specific exclusions in the repo or space settings
## Troubleshooting [#troubleshooting]
| Symptom | Check |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| No models appear in an agent picker | Open Settings → Models and confirm at least one model is enabled. |
| A model appears but a run fails with access errors | Check the account plan, entitlement state, and model availability. |
| The CLI signs in but no shared model list appears | Confirm the web account has model access and that the CLI is using account-backed login. |
| A saved agent references a hidden or stale model | Move it to a visible enabled model in the agent editor. |
| A repo cannot use a globally enabled model | Check repo settings for a repo-specific model exclusion. |
## Read next [#read-next]
* [Settings](/web/settings) for account preferences, access tokens, and models
* [API → Models](/web/api/models) for the route contract behind the catalog
* [Agents](/web/agents) for model choice on reusable agents
* [CLI → Authentication](/cli/guides/authentication) for account-backed model
sync in the CLI
# Observability (/web/observability)
Observability is the runtime view for Mogplex work that has already started.
This is where you answer questions like:
* did the work actually run?
* is the system under pressure, stuck, or failing?
* which model call or tool call caused the problem?
* is cost coming from the CLI, hosted work, or automation?
## The page has two jobs [#the-page-has-two-jobs]
Observability is easiest to use when you treat it as two layers:
* **summary cards** tell you whether the overall system looks healthy
* **Activity** tells you what happened on individual calls
Read the cards first when you want the shape of the problem.
Open Activity rows when you want the actual story.
## What the summary cards show [#what-the-summary-cards-show]
The summary area combines three kinds of signal.
### Job health [#job-health]
* total runs
* currently running runs
* stale pending runs
* failed runs in the last 24 hours
* repaired runs in the last 24 hours
* 24-hour run success rate
### Dispatch pressure and queue health [#dispatch-pressure-and-queue-health]
* suppressed starts in the last 24 hours
* deferred starts in the last 24 hours
* start failures in the last 24 hours
* oldest pending age
### Usage and spend [#usage-and-spend]
* total calls
* calls today
* tokens used
* estimated cost
* average call duration
* call success rate
* total sandbox time plus active and total sandbox counts
That means Observability can tell you whether the problem is broad, isolated,
expensive, or stuck before you inspect a single detailed row.
## What the Activity table shows [#what-the-activity-table-shows]
The main table is call-level, not job-level.
Each row shows:
* **When** the call started
* **Surface**: Live, CLI, Cloud, or Automation
* **Who**: model plus call type
* **Where**: repo context when available
* **IO**: input and output token counts
* **Cost**
* **Duration**
* **Result**
Current table filters are:
* surface
* status
Repo and sandbox filters are also supported through deep links from elsewhere in
the app, such as the sandbox management page or repo-specific drilldowns.
## What the surface badges mean [#what-the-surface-badges-mean]
The surface badge is derived from the call record:
* **Live** means the call is still pending or streaming
* **CLI** means it came from a runtime command in the local CLI path
* **Cloud** means it ran outside a job-backed automation
* **Automation** means it is attached to a job run
That split is the quickest way to answer whether failures or spend are coming
from local work, hosted work, or automation.
## Expand a row when you need the real story [#expand-a-row-when-you-need-the-real-story]
Opening a call row exposes the details Mogplex captured for that call, which
can include:
* a GitHub deep link when the source metadata maps back to a PR, issue, or
related event
* managed sandbox access details, optional linked Vercel project metadata,
sandbox record ID, preview URL, and runtime ID
* a shortcut to open sandbox health directly
* runtime command ID when the call came from the CLI path
* the error string, if the call failed
* an event timeline
* tool calls with captured inputs and outputs
* raw metadata for deeper inspection
This is the part of the app that answers questions like “what tool did the
agent call?”, “which sandbox did this run touch?”, and “what GitHub object did
this call come from?”
## Practical workflows [#practical-workflows]
### A sandbox-backed run looks unhealthy [#a-sandbox-backed-run-looks-unhealthy]
1. Open the relevant call row.
2. Inspect managed sandbox access and preview metadata.
3. Jump straight to sandbox health from the row instead of debugging the model
call in isolation.
### Cost or token usage jumped unexpectedly [#cost-or-token-usage-jumped-unexpectedly]
1. Read the summary cards first to confirm whether this is broad or isolated.
2. Filter Activity by surface or status.
3. Inspect the most expensive or highest-token calls and look at tool usage in
expanded rows.
### A trigger, assignment, or automation seems quiet [#a-trigger-assignment-or-automation-seems-quiet]
1. Check whether the summary cards show runs, stale pending work, suppression,
or start failures.
2. If no relevant call appears in Activity, go back to the source surface:
[Triggers](/web/triggers), [Assignments](/web/assignments), or
[Automations](/web/automations).
## What Observability does not own [#what-observability-does-not-own]
Observability is for inspection after work has queued or started.
Creation, enable or disable state, and routing changes still belong to the
source surfaces:
* [Projects](/web/spaces)
* [Triggers](/web/triggers)
* [Assignments](/web/assignments)
* [Automations](/web/automations)
* [Sandboxes](/web/sandboxes)
## Read next [#read-next]
# Primitives (/web/primitives)
The legacy `/primitives` route still exists in the app, but it now forwards to
the current agent-library surfaces.
It resolves to one of these destinations:
* `/agents/skills` by default
* `/agents/rules` when the old link asked for the rules tab
* `/agents/context` when the old link asked for the context tab
Use those pages for the current product behavior.
## Current mapping [#current-mapping]
If you are cleaning up old bookmarks or internal references, this is the
redirect map the app uses today:
* `/primitives` -> skills
* `/primitives?tab=rules` -> rules
* `/primitives?tab=context` -> context
Unlike `/library`, this route does not forward to the models tab in Settings.
## Why the route still exists [#why-the-route-still-exists]
Older navigation used `/primitives` as an entrypoint into the reusable agent
building blocks.
Mogplex now exposes those pieces directly under [Agents](/web/agents), but the
redirect remains so existing links still land on a valid current surface.
## What the old Primitives concept became [#what-the-old-primitives-concept-became]
The older route now maps onto these current pages:
* [Skills, Rules, and Context](/web/agents/skills-rules-context) for the
current explanation of how these surfaces split up
* [Library](/web/library) when you are untangling older links that also used
the broader `/library` naming
## Rule of thumb [#rule-of-thumb]
If the old reference was about reusable behavior or shared knowledge, it now
belongs under [Agents](/web/agents), not under one standalone `/primitives`
surface.
# Projects (Legacy Docs Route) (/web/projects)
This page exists for older links that still point to the original Projects
docs.
The current dashboard route is `/spaces`, and the active documentation lives at
[Projects](/web/spaces).
## Why this page still exists [#why-this-page-still-exists]
Mogplex kept the product language around **Projects**, but the route itself now
lives under `/spaces`. Older docs links, bookmarks, and internal references can
still land here, so this page stays in place to point them at the current docs.
## Current route language [#current-route-language]
* UI label: **Projects**
* Current route: `/spaces`
* Active docs page: [Projects](/web/spaces)
## What changed [#what-changed]
Older docs and saved links often assumed the docs and product route would both
be called `projects`.
That is no longer true:
* the UI still says **Projects**
* the product route is `/spaces`
* the current documentation is [Projects](/web/spaces)
## Start from the current page when you need to answer questions like: [#start-from-the-current-page-when-you-need-to-answer-questions-like]
* Which repositories are in Mogplex right now?
* Which project or workspace should this repo belong to?
* Is preview infrastructure linked and healthy for this repo?
* Where should I open a workspace session or assign recurring work?
For the full current behavior, including sandbox launch, workspace opening, and
repo organization, use [Projects](/web/spaces).
# Sandboxes (/web/sandboxes)
Sandboxes is the cross-repo runtime view for Mogplex previews.
In the app, this surface lives at `/spaces/sandboxes`. Use it when
[Projects](/web/spaces) is too repo-centric and you need to operate the
sandbox fleet directly.
## Use Sandboxes when [#use-sandboxes-when]
* you need one list of live and pending sandboxes across repos
* a preview is stuck in creating or installing and you want manual override
* you need to open a workspace pinned to one specific sandbox instance
* you want to jump straight from a sandbox to health or observability
* you need to stop or remove stale sandbox records after the repo work moved on
If you are still choosing the repo or changing repo settings, start from
[Projects](/web/spaces). If you already know the failing call or job, move into
[Observability](/web/observability).
## What the page actually shows [#what-the-page-actually-shows]
The current page supports:
* search by repo, branch, preview URL, or status
* a status filter for **Live + pending** versus **All**
* status-first sorting, with running sandboxes shown before installing,
creating, error, and older inactive records
* repo, working branch, base branch, preview URL, and last-activity cues
* direct actions for opening the workspace, opening health, stopping a
sandbox, deleting the record, and refreshing the list
That makes it the operational answer to:
**Which preview runtime is actually alive right now?**
## What the main actions do [#what-the-main-actions-do]
### Open workspace [#open-workspace]
This opens a workspace session pinned to that sandbox and lands you back in the
main app with preview focus already attached to the chosen runtime.
Use it when the repo has more than one recent sandbox branch and you want to be
certain you are attaching to the right one.
### Health [#health]
This opens the same repo workspace pinned to that sandbox, but focuses the
preview health view instead of the normal preview tab.
Use it when the runtime exists but the preview still looks unhealthy.
### Observability [#observability]
Each sandbox can deep-link into [Observability](/web/observability) with the
repo and sandbox record preselected.
That is the path when you need the call, job, and cost trail behind a runtime
problem instead of only the preview state.
### Stop [#stop]
Use **Stop** for a sandbox that is still running, creating, or installing and
should not keep consuming time or billing.
### Delete [#delete]
**Delete** removes the sandbox record and does a best-effort teardown of the
remote sandbox.
Use it for stale or broken records you no longer need to keep around.
## How Sandboxes relates to Projects [#how-sandboxes-relates-to-projects]
[Projects](/web/spaces) is still where sandbox launch usually begins.
Use Projects when you need to:
* pick the repo
* change repo settings like root directory, dev command, env mapping, or
timeout
* start preview from the repo card
* open a normal workspace without caring which sandbox instance backs it
Use Sandboxes when you already know the runtime is the thing you need to
inspect or control.
## Common situations [#common-situations]
### A preview never becomes healthy [#a-preview-never-becomes-healthy]
1. Open Sandboxes and filter to **Live + pending**.
2. Find the repo or working branch.
3. Open **Health** if the runtime exists but the preview looks wrong.
4. Open [Observability](/web/observability) if you need the linked call, job,
or sandbox record details.
### A repo has multiple recent sandbox branches [#a-repo-has-multiple-recent-sandbox-branches]
Open Sandboxes instead of guessing from Projects. The list shows the working
branch directly, which is often the fastest way to tell which runtime matches
the work you care about.
### A sandbox is clearly stale [#a-sandbox-is-clearly-stale]
Use **Delete** when the record should disappear entirely. Use **Stop** when you
want to halt the current runtime but keep the record around long enough to
inspect it.
## Failure modes that matter [#failure-modes-that-matter]
* **A repo exists but no sandbox row does**: the runtime likely never launched;
go back to [Projects](/web/spaces) and start from the repo card.
* **A sandbox row exists but workspace open feels wrong**: open the workspace
from the sandbox row so the session binds to the exact runtime you meant.
* **Preview is up but the run trail is still unclear**: jump to
[Observability](/web/observability) from the sandbox context instead of
debugging from the repo alone.
* **Delete feels destructive**: it is meant for stale or broken runtime
records, not for routine day-to-day stop and start control.
# Settings (/web/settings)
Settings is the account-level control plane for Mogplex.
If something about your identity, repo coverage, model access, shared tools, or
CLI sync looks wrong, this is the first page to inspect.
## Use this page to fix account problems, not routing logic [#use-this-page-to-fix-account-problems-not-routing-logic]
Settings is where you answer questions like:
* can Mogplex actually act on behalf of this GitHub user or org?
* does the account plan include hosted model and sandbox access?
* are the shared MCP or REST connections healthy?
* why did the CLI sign in, but not inherit the hosted state I expected?
If the question is “what should run for this repo?”, use
[Projects](/web/spaces), [Assignments](/web/assignments),
[Triggers](/web/triggers), or [Automations](/web/automations) instead.
## Set these up first [#set-these-up-first]
For a new account, the most reliable order is:
1. connect GitHub
2. install the Mogplex GitHub App for the personal account or orgs that own the
repos you want to use
3. confirm the account plan includes the model and sandbox access you need
4. add shared connections or MCP servers after the account basics are working
5. generate CLI or API access tokens only when the CLI or scripts need to
authenticate as Mogplex itself
That order keeps you from debugging downstream surfaces before the account can
actually support them.
## What lives here [#what-lives-here]
Settings currently groups together:
* **Account** state for GitHub identity, GitHub App coverage, and account
readiness
* **Connections** for REST APIs and MCP servers your agents can use
* **Slack** for workspace install, channel-to-repo links, and repo-agent
controls
* **Access Tokens** for CLI, API, and script authentication
* **Preferences** for theme and default model
* **Models** for the hosted model catalog your account can actually use
For the model-specific operating guide, see
[Available Models](/web/models).
For the connection-specific operating guide, see
[Connections and MCP](/configure-and-extend/connections-and-mcp).
## Start at the top of the page first [#start-at-the-top-of-the-page-first]
The top of Settings is intentionally opinionated.
It is the part of the product that tells you:
* whether GitHub is connected at all
* whether the GitHub App is installed on the right owner
* whether synced repos exist yet
* whether billing, model access, or sandbox access still needs action
* what the next most likely setup step is
Treat that top block as the “what is missing?” answer before you debug any
deeper form.
## Account section [#account-section]
The top of Settings is intentionally operational, not decorative.
It shows:
* current GitHub connection mode and status
* GitHub App coverage and synced repo counts
* the next recommended setup step, such as connecting GitHub, finishing App
install, or syncing repos into Projects
* account access state for hosted model and sandbox work
Two distinctions matter here:
* **GitHub OAuth** is about account identity and repo discovery
* **GitHub App coverage** is what makes repos triggerable for reviews,
automations, and webhook-backed routing
If a repo shows up in [Projects](/web/spaces) but still cannot participate in
[Triggers](/web/triggers) or automation, the usual cause is missing App
coverage for that owner.
## Billing and Access [#billing-and-access]
Hosted model calls and sandbox usage are billed through Mogplex.
Users do not need external model credentials or external sandbox accounts for
normal hosted work. If a model picker is empty or a sandbox cannot launch
because access is missing, check the account plan or entitlement state before
editing agents, prompts, or repo launch settings.
See [Plans & Billing](/plans-and-billing) for the stable billing entry point.
## GitHub App coverage details [#github-app-coverage-details]
The GitHub App coverage block shows more than a binary yes/no.
For each installation, Mogplex can show:
* the account or org name
* the installation scope
* how many repos Mogplex has associated with that installation
* a GitHub manage link when one can be derived
* the list of synced repos under that installation
This is the fastest way to answer a common setup problem:
**Can Mogplex merely see this repo, or is it actually covered for App-backed
work?**
## Connections [#connections]
Connections are where you register the non-model systems agents can call.
Connections is about **inbound** integrations — Mogplex calling external systems. For the opposite direction — external agents calling into Mogplex — see [Extend](/extend): Skills today, the [MCP server](/extend/mcp-server) in preview.
Mogplex supports two connection categories:
* **REST API** connections
* **MCP Server** connections
The page supports:
* quick-add MCP presets
* fully custom REST or MCP endpoints
* auth modes including none, bearer token, API key, basic auth, and OAuth
* testing a connection after setup
* enable, disable, reconnect, or remove actions
The operational rule here is simple:
configure and test the integration in Settings first, then debug agent prompts
or routing only after the connection itself is known-good.
Settings is also only part of the story.
When you are inside an active repo workspace, Mogplex can resolve connections
with repo context:
* **Global** connections stay available everywhere by default
* **This Project** connections only exist for one repo
* one repo can explicitly exclude a global connection without deleting it
account-wide
Use Settings to onboard and validate the integration itself. Use the repo
context when one codebase needs a different tool surface. For the full
configuration model, see
[Connections and MCP](/configure-and-extend/connections-and-mcp) and
[Connection Scope and Overrides](/web/guides/connection-scope-and-overrides).
### Current MCP quick-add presets [#current-mcp-quick-add-presets]
The built-in MCP presets currently include:
* Zapier
* Notion
* Supabase
* Browserbase
* Sentry
* Sanity CMS
* Linear
Some presets use direct credentials, while others use an OAuth flow. Settings
surfaces the connection health state and last-tested metadata so you can fix the
integration before debugging agent prompts.
## Slack [#slack]
The Slack section installs the Mogplex Slack app and manages workspace-level
Slack behavior.
Use it to:
* install or disconnect Slack workspaces
* link Slack channels to Mogplex repos
* enable or disable Slack-started repo-agent runs
* restrict repo-agent runs to specific Slack user IDs
* set a monthly Slack repo-agent run limit
Linked channels change `@mogplex` behavior. In an unlinked channel, Mogplex can
reply conversationally. In a linked channel, a real instruction after
`@mogplex` starts a repo-agent run against the linked repo.
For the full Slack model, see [Slack](/integrations/slack).
## Access Tokens [#access-tokens]
Access tokens are for authenticating Mogplex clients and scripts. They are not
model-provider credentials.
Use them when the CLI or another Mogplex-aware script needs to authenticate as
you against Mogplex itself.
The section supports:
* naming each token
* optional expiration windows
* one-time token display at creation
* copy-on-create flow
* last-used metadata
* revocation
Hosted model and sandbox access comes from the account plan, not from
user-supplied provider or sandbox credentials.
## Preferences and Models [#preferences-and-models]
Settings also owns the user-level defaults that affect hosted behavior and sync
surfaces.
The important split is:
* **Models section** controls what models are available to the account
* **Agent settings** choose which available model a specific agent should use
If an agent cannot select the model you expect, check **Models** before you
edit the agent itself.
Use [Available Models](/web/models) when you need the fuller model-access
mental model: enabled state, defaults, plan access, CLI sync, hidden legacy
models, and repo-level exclusions.
## Fast troubleshooting map [#fast-troubleshooting-map]
* **Triggers page is empty**: GitHub OAuth may be connected, but App coverage is
missing for the repo owner.
* **The CLI signs in but no shared models or MCP entries appear**: the Mogplex
account exists, but the hosted account may still lack model access or shared
connection setup.
* **A connection exists but agent calls still fail**: test the connection here
before debugging prompts or routing.
* **Slack replies but does not start repo work**: check channel-to-repo links,
repo-agent enabled state, Slack user mapping, and monthly/user limits in the
Slack section.
* **Sandbox launch says access is unavailable**: check the account plan and
entitlement state before changing repo settings.
* **The repo is visible, but webhook-backed work still does not fire**:
visibility and App-backed coverage are different states. Check the
installation list here first.
## Why Settings matters [#why-settings-matters]
The web app and CLI share parts of this control plane.
The cleanest Mogplex setup is to wire shared account state here once, then let
the CLI reuse that state for synced models, shared MCP configuration, and
account-backed login.
# Projects (/web/spaces)
In the Mogplex app, the top-bar label is **Projects** and the route is
`/spaces`.
This page is the operational starting point for repo-backed work. It is where
repo discovery turns into a running workspace, a live preview, or standing
automation attached to a specific repository.
## Mental model [#mental-model]
* A **repo** is the imported GitHub repository Mogplex knows about.
* A **project** is the grouping layer shown in the UI. Under the hood, this is
a workspace record that holds shared sandbox defaults.
* A **workspace session** is the live chat/editor/terminal session you open for
a repo.
* A **sandbox** is the runtime and preview environment attached to that repo
work.
## What Projects actually manages [#what-projects-actually-manages]
Use Projects when you need to:
* sync imported repositories and search them quickly
* group repos into projects and organize the list
* favorite repos, hide noisy repos, or filter by owner
* start or stop a preview sandbox
* open a workspace session for a repo
* add monorepo sub-project entries instead of forcing one root for the whole
repo
* create repo-bound work such as assignments or cron-backed automation
* edit repo settings, secrets, and snapshots
Opening a workspace is not a passive navigation step. If the repo does not
already have a running sandbox, Mogplex can launch one first and then bind the
workspace session to it automatically.
## Repo card quick actions [#repo-card-quick-actions]
Each repo card can surface:
* preview state such as live, starting, unreachable, idle, or error
* the current working branch when a sandbox exists
* effective sandbox timeout and preview port hints
* assigned agents and cron schedules
* quick actions for **Open workspace**, **Start Preview**, **Stop Preview**,
**Assign Agent**, **Create Cron**, **Settings**, **Favorite**, and **Hide**
If you need a cross-repo list of running or pending sandboxes, use
[Sandboxes](/web/sandboxes).
## Repo settings you can control [#repo-settings-you-can-control]
The repo settings dialog has three tabs.
### General [#general]
General settings are where you control the runtime shape for that repo:
* managed sandbox access state for hosted workspace launches
* repo-linked Vercel team and Vercel project
* env mapping mode: sandbox only, sandbox + preview conventions, or sync from a
linked Vercel project
* root directory for monorepos or sub-projects
* install command, dev command, and dev port
* sandbox timeout override
* manual environment variables in `.env`-style `KEY=value` format
### GitHub Secrets [#github-secrets]
Use this tab when the repo needs GitHub secret configuration managed alongside
its Mogplex setup.
### Snapshot [#snapshot]
Use this tab to inspect the repo snapshot state Mogplex is using for sandbox
work.
## A practical first workflow [#a-practical-first-workflow]
1. Connect GitHub in [Settings](/web/settings).
2. Confirm the right user or org has Mogplex GitHub App coverage in
[Installations](/web/installations).
3. Sync repos and find the target repo in Projects.
4. Open repo settings if you need to set a root directory, dev command, preview
port, or optional Vercel metadata before boot.
5. Open the workspace. If no sandbox is running yet, Mogplex can launch it as
part of that action.
6. From the repo card, choose the next layer:
* stay in the live workspace for interactive work
* create a repo-bound [Assignment](/web/assignments)
* add a [Trigger](/web/triggers) when routing should be installation-wide
* move to [Automations](/web/automations) for multi-step flows
## Monorepos and sub-projects [#monorepos-and-sub-projects]
Projects has explicit support for monorepos.
If a repo has multiple app or package entrypoints, use the monorepo browser to
scan detected workspaces and add sub-project repos for specific
`root_directory` paths. That keeps preview commands, env mapping, and sandbox
settings aligned to the actual app you want to run.
If automatic detection misses the right target, set `root_directory` manually
in repo settings.
## Sandbox management [#sandbox-management]
Projects is where sandbox launch usually starts, but it is not the only sandbox
surface.
Use [Sandboxes](/web/sandboxes) when you need a cross-repo operational view
of running or pending previews, or when you want manual override on a specific
sandbox instead of going through the repo card.
## Failure modes that matter [#failure-modes-that-matter]
* **Repo is visible but trigger-backed features do not work**:
GitHub OAuth is connected, but the correct GitHub App installation is
missing.
* **Open workspace feels slow the first time**:
the repo probably needs its sandbox created or installed first.
* **Sandbox launch says access is unavailable**:
the account plan may not include managed sandbox access yet.
* **Preview opens the wrong app in a monorepo**:
create a sub-project repo or set `root_directory`, `dev_command`, and
`dev_port` explicitly.
* **A repo disappeared from the main list**:
it may be hidden. Toggle removed repos back on from the Projects controls.
## Related surfaces [#related-surfaces]
* [Installations](/web/installations) explains GitHub App coverage and repo
triggerability.
* [Assignments](/web/assignments) is for standing repo-to-agent work.
* [Triggers](/web/triggers) is for installation-scoped event routing.
* [Observability](/web/observability) is where you inspect cost, calls,
sandbox linkage, and runtime health after work starts.
# Triggers (/web/triggers)
Triggers are the lightest routing surface for GitHub events.
Use them when the rule is simply:
`one event -> one agent`
If you need branching, delays, multiple agents, or a draft/publish workflow,
move up to [Automations](/web/automations).
## Why Triggers exists [#why-triggers-exists]
Triggers is the “do the obvious thing” surface.
It is for cases where you do not need a canvas, a repo-owned standing contract,
or a multi-step workflow. You just need one GitHub event on one installation to
wake one agent reliably.
## What a trigger binds [#what-a-trigger-binds]
Each trigger binds:
* one GitHub App installation
* one supported event type
* one agent
* an enabled or disabled state
* for mention triggers only, whether bare `@mogplex` mentions should route here
Triggers are installation-scoped, not repo-scoped. They listen to webhook
events from the selected GitHub App installation and then dispatch to the
chosen agent.
That scope is the main reason to choose Triggers over
[Assignments](/web/assignments): the installation is the source of truth, not a
single repo.
## Supported events [#supported-events]
Current trigger events are:
* `@mention`
* pull request opened
* issue opened
* pull request comment
* issue comment
* push
* CI failure
## Choose Triggers vs Assignments vs Automations [#choose-triggers-vs-assignments-vs-automations]
* Use **Triggers** when the rule should apply at the installation event layer.
* Use **Assignments** when a single repo should own standing work like PR
review, CI failure response, or cron.
* Use **Automations** when one event should branch, delay, fan out, or publish
as a workflow graph.
## Requirements [#requirements]
Triggers only work for repos covered by an installed GitHub App.
GitHub OAuth on its own is not enough. If the page is empty, or the creation
form says no installations are available, check
[Installations](/web/installations) and confirm the correct user or org has the
Mogplex GitHub App installed.
The creation form searches installations by both account scope and synced repos,
so this page is often the fastest way to notice that repos are synced but still
not webhook-covered.
## How to create a good trigger [#how-to-create-a-good-trigger]
When you create a trigger, the practical sequence is:
1. choose the GitHub App installation that owns the repos you care about
2. choose the event type that should wake work
3. choose the agent that should respond
4. for mention routes, decide whether this is the default route for bare
`@mogplex`
Keep the rule as narrow as possible. If you feel tempted to explain branches,
follow-up steps, or parallel work in prose, the route probably belongs in
[Automations](/web/automations) instead.
## How creation works [#how-creation-works]
When you create a trigger, the form asks for:
1. the GitHub App installation to listen on
2. the event type
3. the agent to wake up
If the event is `@mention`, the form also shows whether the route should be the
default for bare `@mogplex` mentions. That toggle only exists for mention
triggers because it is not meaningful for the other event types.
If the selected agent already has a slug, the form shows the exact targeted
mention handle, such as `@mogplex/triage`. When you save the trigger, Mogplex
ensures the agent has a slug so targeted mention routing can resolve
consistently.
## Mention routing rules [#mention-routing-rules]
The most important detail is that GitHub mention syntax is exact.
* `@mogplex` is a bare mention
* `@mogplex/` is a targeted mention
Example:
```text
@mogplex/triage summarize this PR thread and suggest next steps.
```
Rules:
* Bare `@mogplex` only routes to mention triggers marked as the default for
that installation.
* `@mogplex/` targets the trigger whose agent slug matches the text
after `/`.
* The slash matters. `@mogplex triage` is not the same as
`@mogplex/triage`.
* Mention routing comes from GitHub comment events, not from issue titles or PR
titles.
For the full mention model, see
[GitHub Mention Routing](/web/guides/github-mention-routing).
## What healthy trigger operations look like [#what-healthy-trigger-operations-look-like]
Existing triggers are grouped by installation and show live operating signals,
including:
* enabled or disabled state
* the event badge and selected agent
* the agent slug when targeted mention routing is possible
* last run status and timestamp
* failed, running, pending, suppressed, and deferred counts
* the latest pressure reason when dispatch was intentionally held
* whether a mention trigger is the default target for bare `@mogplex`
The page is optimized for fast routing edits, so enable/disable and delete are
inline instead of hidden in a deeper detail view.
That means the trigger row is not just configuration. It is also the first
operational summary for whether the route is alive, under pressure, or failing.
## Good fits for Triggers [#good-fits-for-triggers]
Use Triggers when you want a direct event-to-agent mapping, for example:
* wake a review agent when a pull request opens
* wake a triage agent when a CI run fails
* route `@mention` events to a default repo assistant
* target a specific agent with `@mogplex/`
If the durable unit is a specific repo instead of an installation, use
[Assignments](/web/assignments). If the workflow needs conditions, branches, or
multiple steps, use [Automations](/web/automations).
## Common mistakes [#common-mistakes]
* writing `@mogplex triage` instead of `@mogplex/triage`
* expecting OAuth-synced repos to appear before GitHub App coverage exists
* using Triggers when the logic really belongs to one repo and should be an
[Assignment](/web/assignments)
* assuming bare `@mogplex` will route anywhere without a default mention route
## If routing does not fire [#if-routing-does-not-fire]
Check these in order:
1. the repo is covered by the correct GitHub App installation
2. the trigger is enabled
3. the event type matches what actually happened
4. if this is a mention:
* bare `@mogplex` has a default mention route on that installation
* targeted `@mogplex/` matches the agent slug exactly
5. if the route still looks idle, inspect [Observability](/web/observability)
for call activity and then return to the trigger row for pressure signals
# CI integration (/cli/automation/ci-integration)
The CLI is suitable for CI any time you want to delegate code-change work to a
Mogplex agent — for example, opening cleanup PRs on a schedule, applying a
codemod against a list of repos, or driving "dispatched" automation runs from
a workflow.
## Prereqs [#prereqs]
1. A PAT with the `write` scope, issued at
[mogplex.com/settings/api-keys](https://www.mogplex.com/settings/api-keys).
2. Store the token in your CI's secret store. Never commit it.
3. Pick the repo ID(s) you want to operate on:
```bash
MOGPLEX_API_KEY=mog_... mogplex repos list
```
## GitHub Actions example [#github-actions-example]
A scheduled workflow that asks Mogplex to keep dependencies fresh weekly. The
workflow itself only installs the CLI, then delegates everything to the agent.
```yaml
# .github/workflows/mogplex-weekly-cleanup.yml
name: Mogplex weekly cleanup
on:
schedule:
- cron: "0 12 * * 1" # Mondays 12:00 UTC
workflow_dispatch:
jobs:
cleanup:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- name: Install mogplex CLI
run: |
curl -fsSL https://install.mogplex.com/install.sh | sh
mogplex --help | head -1
- name: Start cleanup run
id: start
env:
MOGPLEX_API_KEY: ${{ secrets.MOGPLEX_API_KEY }}
MOGPLEX_REPO_ID: ${{ vars.MOGPLEX_REPO_ID }}
run: |
set -euo pipefail
RUN=$(
mogplex run \
--repo "$MOGPLEX_REPO_ID" \
--harness codex \
--create-branch \
--idempotency-key "weekly-cleanup-$(date -u +%Y-%m-%d)" \
--json \
"Run the dependency cleanup checklist. Update minor/patch versions, run tests, open a PR if changes pass." \
| jq -r '.runId'
)
# mogplex exits non-zero on API failure, but guard against an empty
# runId (e.g. unexpected response shape) so downstream steps don't
# call `runs events ''` with a confusing error.
[ -n "$RUN" ] && [ "$RUN" != "null" ] || { echo "Failed to extract run ID"; exit 1; }
echo "run_id=$RUN" >> "$GITHUB_OUTPUT"
echo "Started run $RUN"
- name: Tail events
env:
MOGPLEX_API_KEY: ${{ secrets.MOGPLEX_API_KEY }}
run: |
mogplex runs events "${{ steps.start.outputs.run_id }}" \
--follow --timeout 1500
- name: Report final status
if: always()
env:
MOGPLEX_API_KEY: ${{ secrets.MOGPLEX_API_KEY }}
run: |
STATUS=$(
mogplex runs get "${{ steps.start.outputs.run_id }}" --json \
| jq -r '.status'
)
echo "::notice::Final run status: $STATUS"
[ "$STATUS" = "success" ]
```
A few details worth calling out:
* **Idempotency key** is derived from the date so a manual `workflow_dispatch`
retry on the same day replays the original run instead of starting a fresh
one. Change the date in the key to force a new run.
* **`--create-branch`** ensures Mogplex commits to a generated working branch
rather than the repo's default branch. The agent's PR draft surfaces in the
Mogplex web UI and (depending on your repo setup) is opened on GitHub
automatically.
* **`if: always()`** on the report step makes the final status visible even if
the tail step exits non-zero (timeout, cancellation, transient).
* **No `actions/checkout`** — the workflow doesn't need a working copy. Mogplex
drives the repo from the cloud sandbox.
## Secret handling [#secret-handling]
Three secrets matter for typical CI use:
| Secret | Required? | Notes |
| ----------------- | --------- | -------------------------------------------------------- |
| `MOGPLEX_API_KEY` | yes | PAT with `write` scope. Store as a repository secret. |
| `MOGPLEX_REPO_ID` | no | If you only run against one repo, store as a variable. |
| `MOGPLEX_URL` | rarely | Override only when targeting a staging Mogplex instance. |
PATs are bearer tokens with no audience check. Don't reuse the same token
across CI for unrelated projects — issue one per project so a leak from one
repo doesn't compromise the others. Revoke compromised tokens at
[settings/api-keys](https://www.mogplex.com/settings/api-keys).
## Retry pattern for transient failures [#retry-pattern-for-transient-failures]
```bash
attempt=0
until mogplex runs events "$RUN_ID" --follow --timeout 600 ; do
rc=$?
attempt=$((attempt + 1))
case "$rc" in
75) sleep $((30 * attempt)) ;; # rate-limited; back off
69) sleep 60 ;; # service unavailable; wait
64|65) echo "auth issue (exit $rc)"; exit "$rc" ;;
*) echo "non-retryable (exit $rc)"; exit "$rc" ;;
esac
if [ "$attempt" -ge 3 ]; then
echo "giving up after $attempt attempts"
exit "$rc"
fi
done
```
Exit codes (64 unauth, 65 forbidden, 69 service unavailable, 75 rate-limited)
let CI scripts distinguish "fix your token" from "wait and retry." See
[Automation overview → Exit codes](/cli/automation#exit-codes).
The CLI does not surface the raw `Retry-After` response header, so the sleep
values above are conservative defaults rather than server-directed waits. If
you call the API directly with `curl`, parse `Retry-After` from the response
and honor it — see [API → Errors](/web/api/errors) and
[API → Authentication](/web/api/authentication).
## Read-only dashboards [#read-only-dashboards]
For dashboards or metric collectors that should never start a run, issue a
read-only PAT (scope `["read"]`) and use the listing commands:
```bash
mogplex repos list --json | jq '. | {id, full_name}'
mogplex sandboxes list --json | jq 'select(.status == "running")'
```
A read-only PAT hitting `mogplex run` exits with code `65` (forbidden) and a
`FORBIDDEN` error code — useful as a fail-safe guardrail.
## Read next [#read-next]
* [Headless runs](/cli/automation/headless-runs) — the full command reference
* [API → Authentication](/web/api/authentication) — PAT scope model and rate limits
* [API → Errors](/web/api/errors) — error codes and retry guidance
# Headless runs (/cli/automation/headless-runs)
The `mogplex run` / `mogplex runs` commands cover the full agent-run lifecycle
from any shell. They wrap the [v1 runs API](/web/api/runs) one-for-one and
add the conveniences you'd want in CI: auto-generated idempotency keys,
streaming output, and exit-code-mapped errors.
## Prereqs [#prereqs]
A PAT with the `write` scope (start/cancel require it; get/events require `read`):
```bash
export MOGPLEX_API_KEY="mog_..."
```
Issue one at [mogplex.com/settings/api-keys](https://www.mogplex.com/settings/api-keys).
Issue a read-only token for dashboards that should never start runs.
## Start a run [#start-a-run]
```bash
mogplex run --repo "Refactor the auth module to use bearer tokens."
```
Output (pretty):
```
started run run-uuid (pending)
repo 8f3a2b1c-1234-4abc-9def-1234567890ab
harness codex
branch mogplex/run/2026-05-17/refactor-auth (base main, created)
tail events: mogplex runs events run-uuid --follow
```
### Required flag [#required-flag]
`--repo ` — get repo IDs from `mogplex repos list`. Without it the CLI
exits with `2` (usage error) and the message:
```
error: run: --repo is required (find IDs via `mogplex repos list`)
```
### Common flags [#common-flags]
| Flag | Default | Notes |
| --------------------------------- | ----------------------- | -------------------------------------------- |
| `--harness codex` / `claude-code` | server-chosen (`codex`) | Picks the agent runtime |
| `--base-branch ` | repo default branch | Base for `--create-branch` work |
| `--branch ` | inherits from base | Working branch the agent commits to |
| `--create-branch` | `false` | If set, creates the working branch from base |
| `--root ` | repo root | Monorepo subpath |
| `--idempotency-key ` | auto UUID | Pass when orchestrating retries yourself |
| `--json` | pretty | Emit the full API envelope as one JSON line |
### Idempotent retries [#idempotent-retries]
Re-running `mogplex run` with the same `--idempotency-key` and same body
returns the original run with `matched existing run …` instead of `started`.
```bash
KEY=$(uuidgen)
# First call — starts the run
mogplex run --repo $REPO --idempotency-key "$KEY" "Fix flaky tests"
# → started run run-abc (pending)
# Network glitch, retry — replays the same run
mogplex run --repo $REPO --idempotency-key "$KEY" "Fix flaky tests"
# → matched existing run run-abc (pending)
```
Same key with a different body fails fast with exit code 1 + an envelope
error code of `IDEMPOTENCY_CONFLICT`.
### JSON output [#json-output]
```bash
mogplex run --repo $REPO --json "Fix flaky tests"
```
Emits one line of JSON — the
[`StartMogplexApiAgentRunResult`](/web/api/runs#start-a-run) object with
top-level fields like `runId`, `status`, `repoId`, and `branch`. The CLI
unwraps the REST `{ok, data}` envelope for you, so jq paths are flat:
```bash
RUN_ID=$(mogplex run --repo $REPO --json "Fix flaky tests" | jq -r '.runId')
```
## Inspect a run [#inspect-a-run]
```bash
mogplex runs get
```
```
run run-uuid
status streaming
harness codex
repo 8f3a2b1c-...
branch feat/x (base main, created)
sandbox vsb_abc
events /api/v1/mogplex/runs/run-uuid/events
cancel /api/v1/mogplex/runs/run-uuid/cancel
created 2026-05-17T10:14:00.000Z
updated 2026-05-17T10:15:30.000Z
```
`--json` emits the [`MogplexApiRunDetail`](/web/api/runs#get-a-run) object
with flat top-level fields (`runId`, `status`, etc.) — the REST `{ok, data}`
wrapper is stripped.
## Tail events with `--follow` [#tail-events-with---follow]
```bash
mogplex runs events --follow
```
Pretty output, one event per line:
```
2026-05-17T10:14:10.000Z stream_started Agent started
2026-05-17T10:14:15.000Z tool_call tool=edit_file Editing src/auth.ts
2026-05-17T10:14:22.000Z tool_result tool=edit_file 3 lines changed
2026-05-17T10:14:30.000Z assistant_message Switching to bearer-token middleware
...
--- run run-uuid success ---
```
`--follow` polls every 1.5s, de-dupes events by ID, and exits when the run
reaches a terminal status (`success`, `failed`, `cancelled`). A trailing line
prints the final status.
### Timeout [#timeout]
```bash
mogplex runs events --follow --timeout 600 # 10 minutes
```
`--timeout` is a wall-clock cap in seconds. Default `1800` (30 minutes).
Hitting the timeout prints:
```
error: --follow timed out after 600s waiting for terminal status
```
…and exits with code `1`. The run keeps going on the server — re-run
`mogplex runs events --follow` to resume tailing.
### JSON streaming [#json-streaming]
```bash
mogplex runs events --follow --json
```
One [`PresentedAiCallEvent`](/web/api/runs#list-run-events) per line. The
final line is `{"runId":"...","status":"success"}`. Perfect for piping into
`jq`, a structured log shipper, or a CI annotation step.
The events feed is sanitized server-side: sensitive payload keys are redacted,
strings/arrays/objects are capped. Safe to dump into a public CI log without
leaking credentials or session tokens.
## Cancel a run [#cancel-a-run]
```bash
mogplex runs cancel
```
```
cancellation requested for run run-uuid
status: cancellation_requested
```
Idempotent — cancelling a run that's already terminal returns the terminal
state with no side effects.
## End-to-end sketch [#end-to-end-sketch]
```bash
#!/usr/bin/env bash
set -euo pipefail
REPO_ID="${MOGPLEX_REPO:?set MOGPLEX_REPO to a UUID from \`mogplex repos list\`}"
RUN_ID=$(
mogplex run --repo "$REPO_ID" --create-branch --json \
"Apply the linter autofixes and commit them" \
| jq -r '.runId'
)
echo "started run $RUN_ID"
mogplex runs events "$RUN_ID" --follow --timeout 900
STATUS=$(mogplex runs get "$RUN_ID" --json | jq -r '.status')
case "$STATUS" in
success) echo "✓ run succeeded" ; exit 0 ;;
cancelled) echo "✗ cancelled" ; exit 1 ;;
failed) echo "✗ failed" ; exit 1 ;;
*) echo "? unexpected status: $STATUS" ; exit 2 ;;
esac
```
## Read next [#read-next]
* [CI integration](/cli/automation/ci-integration) — GitHub Actions worked example
* [API → Runs](/web/api/runs) — the REST endpoints this command wraps
* [API → Errors](/web/api/errors) — error codes mapped to exit codes
# Automation (/cli/automation)
`mogplex` is two things in one binary:
* An **interactive cockpit** (the TUI you get when you run `mogplex` with no
arguments). Covered in [CLI → Quickstart](/cli/quickstart).
* A **headless subcommand surface** for scripts, CI, dashboards, and scheduled
jobs. Covered here.
The dispatch is automatic: if the first argument is a known subcommand
(`repos`, `run`, `runs`, `sandboxes`), the CLI runs headlessly and exits. Any
other invocation boots the TUI.
## When to use which [#when-to-use-which]
| You want to… | Use |
| ------------------------------------------------ | ------------------------------------------------------ |
| Edit code interactively with the agent | `mogplex` (TUI) |
| Start a cloud run from a script or CI step | [`mogplex run`](/cli/automation/headless-runs) |
| Tail a run's events from a CI log | `mogplex runs events --follow` |
| Power a status dashboard with read-only access | `mogplex repos list` + `mogplex sandboxes list --json` |
| Cancel a runaway run from a Slack bot or webhook | `mogplex runs cancel ` |
The headless surface talks to the same `/api/v1/mogplex/*` endpoints
documented under [API Reference](/web/api). The CLI just bundles the typed
client, output formatting, exit codes, and credential resolution.
## Quick start [#quick-start]
```bash
# Set up a personal access token at https://www.mogplex.com/settings/api-keys
export MOGPLEX_API_KEY="mog_..."
# List your repos to find an ID
mogplex repos list
# Start a run
mogplex run --repo --harness codex "Refactor auth to use bearer tokens"
# Tail it
mogplex runs events --follow
```
## Commands [#commands]
| Command | Scope | Purpose |
| ----------------------------- | ------- | --------------------------------------- |
| `mogplex repos list` | `read` | List your cloud-linked repos |
| `mogplex run` | `write` | Start an agent run |
| `mogplex runs get ` | `read` | Get a run's current state |
| `mogplex runs events ` | `read` | List or tail a run's event stream |
| `mogplex runs cancel ` | `write` | Request cancellation |
| `mogplex sandboxes list` | `read` | List cloud sandboxes |
| `mogplex sandboxes stop ` | `write` | Stop a sandbox (placeholder, see below) |
`mogplex sandboxes stop` is a placeholder until the v1 sandbox lifecycle routes
ship. Today it prints a message pointing you at the web UI. The CLI will
switch to the v1 endpoint automatically once it lands.
## Output formats [#output-formats]
Every command supports `--json` for machine-readable output (NDJSON for lists,
single object for `get` / `start` / `cancel`). Without `--json` you get a
human-friendly table or summary.
```bash
mogplex repos list # table
mogplex repos list --json # one JSON repo per line
```
## Auth precedence [#auth-precedence]
```
1. MOGPLEX_API_KEY env var (highest priority)
2. ~/.mogplex/auth.json (from `mogplex` → /login)
```
Set `MOGPLEX_API_KEY` for CI and one-shots (`MOGPLEX_API_KEY=mog_... mogplex
repos list`). The auth.json fallback works without any env setup once you've
signed in via the TUI.
See [Authentication](/web/api/authentication) for PAT issuance, scope model
(`read` / `write`), revocation, expiry, and rate limits.
## Base URL [#base-url]
The CLI hits `https://www.mogplex.com` by default. Override with:
```bash
export MOGPLEX_URL="https://staging.mogplex.com"
```
For local development, set `MOGPLEX_DEV=1` and `NODE_ENV` to something other
than `production` to allow `http://localhost:*`.
## Exit codes [#exit-codes]
The CLI follows clig.dev / sysexits conventions:
| Code | Meaning |
| ---- | --------------------------------------------------------- |
| 0 | Success |
| 1 | Generic failure |
| 2 | Usage error (bad args, unknown subcommand) |
| 64 | Unauthorized (no token / 401) |
| 65 | Forbidden (PAT lacks required scope / 403) |
| 69 | Service unavailable (503) |
| 75 | Temporary failure / rate limited (429) — caller can retry |
Branch on exit codes in shell scripts:
```bash
mogplex runs events "$RUN_ID" --follow
case $? in
0) echo "run completed cleanly" ;;
64) echo "auth failed — refresh MOGPLEX_API_KEY"; exit 1 ;;
65) echo "PAT lacks write scope" ; exit 1 ;;
75) echo "rate limited — backing off" ; sleep 60 ; exec "$0" "$@" ;;
*) echo "unexpected failure (exit $?)" ; exit 1 ;;
esac
```
## Read next [#read-next]
* [Headless runs](/cli/automation/headless-runs) — `mogplex run` and event tailing in detail
* [CI integration](/cli/automation/ci-integration) — GitHub Actions example
* [API → Runs](/web/api/runs) — the REST endpoints the CLI wraps
# Slash Commands (/cli/commands)
The CLI's command surface is **slash commands** in the composer. There are no top-level subcommands beyond bare `mogplex` (open the cockpit) and `mogplex --attach ` (attach mode).
## Run control [#run-control]
| Command | What it does |
| ------------- | -------------------------------------------------------------------------------- |
| `/run ` | Start a new run with the given task as the initial prompt. |
| `/pause` | Pause the active run. Agents stop at the next safe point. |
| `/resume` | Resume a paused run. |
| `/kill` | Cancel the active run. Agents are stopped; in-flight tool calls are interrupted. |
## Surface inspection [#surface-inspection]
| Command | What it does |
| --------- | ------------------------------------------------------------- |
| `/agents` | List agents on the active run with status and current action. |
| `/mcp` | Open the MCP drawer — per-server status and tools. |
| `/memory` | Open the Memory drawer — browse and manage entries. |
| `/diff` | Open the Diff drawer — inspect patches produced by the run. |
| `/cost` | Open the Cost drawer — tokens, cost, projections per agent. |
## Cockpit control [#cockpit-control]
| Command | What it does |
| ----------------------- | -------------------------------------------------------------------------------- |
| `/model` | Open the Model Picker drawer — switch the run's model. |
| `/permissions ` | Set the active permission mode (`approval` or `auto`). Takes effect on next run. |
| `/permissions` | (no arg) Show the resolved permission state and where each rule came from. |
| `/export` | Open the Run Export drawer — serialize the run as JSON, JSONL, or Markdown. |
| `/help` | Open the Command Palette to fuzzy-search every action. |
| `/clear` | Clear the composer. |
| `/quit` (alias `/exit`) | Clean exit. |
## Auth [#auth]
| Command | What it does |
| --------- | ----------------------------------------------------------------- |
| `/login` | Open the in-app login flow. |
| `/logout` | Clear stored Mogplex token. The login screen appears next launch. |
## Composing tasks [#composing-tasks]
Anything that is **not** a slash command is sent to the active agent as a task or follow-up:
```text
> rebuild the validation layer using zod and update the tests
```
If you type a partial slash command, autocomplete candidates appear above the line. Unknown slash commands surface as inline composer errors so you don't accidentally send them as prompts.
## See also [#see-also]
* [Reference → Drawers](/cli/reference/drawers) — what each drawer does once opened.
* [Concepts → Permissions](/cli/concepts/permissions) — what `/permissions ` actually changes.
* [Concepts → Attach](/cli/concepts/attach) — `--attach ` for in-flight runs.
# Approvals (/cli/concepts/approvals)
When the active permission mode is `approval`, tool calls that would touch the workspace, write memory, run commands, delete files, use remote tools, or change the model pause and route through the **Approval drawer**.
## The flow [#the-flow]
```
agent wants to run something
│
▼
permission resolver: allow / ask / deny?
│
├── allow ──► runs immediately, surfaces as a normal timeline event
├── deny ──► auto-rejected, surfaces as a denied event
└── ask ──► joins the approval queue
```
Items in the queue render in the **Approval drawer** with:
* the action and target
* an inferred **risk level** (`low`, `medium`, `high`)
* the agent that requested it
* the tool involved
* a quick approve/reject affordance
## Actions that can be gated [#actions-that-can-be-gated]
Any of these can hit the queue:
| Action | What it usually means |
| ----------------- | -------------------------- |
| `apply_patch` | Apply a code change |
| `write_memory` | Write to long-term memory |
| `run_command` | Execute a shell command |
| `delete_file` | Delete a file or directory |
| `use_remote_tool` | Call a remote MCP tool |
| `change_model` | Switch the model mid-run |
## Risk levels [#risk-levels]
| Level | Examples |
| ---------- | ------------------------------------------------------------- |
| **low** | Read-only commands, dry-run patches |
| **medium** | Writes inside the workspace, shell commands with side effects |
| **high** | Deletes, network calls, anything outside the workspace |
The drawer color-codes by risk so you can scan quickly.
## Approve, reject, batch [#approve-reject-batch]
* **Approve** runs the action immediately and resumes the agent.
* **Reject** marks the action as denied; the agent decides how to proceed (usually picking a different approach).
* **Batch approve** is available when multiple items are queued and obviously related.
The store keeps **optimistic state** — once you approve, the UI assumes success until the event-loop confirms or contradicts. That means the drawer feels instant even if core takes a moment to act.
## Auto-reject [#auto-reject]
If a request matches a `deny` rule from the resolved permissions ([Permissions](/cli/concepts/permissions)), it's **auto-rejected** without ever joining the queue. The denial still appears in the timeline so you can see what was attempted.
## What `auto` mode changes [#what-auto-mode-changes]
In `auto` mode, no requests join the queue — everything runs immediately. This is the explicit user opt-in to "no questions asked" and maps to the most permissive runtime flags. Switch back with `/permissions approval` whenever you want the gates back.
## Where approvals show up [#where-approvals-show-up]
* **Approval drawer** — the queue, opened with `/help` → "Open Approval" or via the command palette.
* **Priority alerts strip** — high-risk pending approvals surface here so they aren't missed if a drawer is closed.
* **Timeline** — every approved/rejected/auto-rejected action appears as a structured event.
## Read next [#read-next]
* [Permissions](/cli/concepts/permissions) — how `allow` / `ask` / `deny` rules are configured.
* [Reference → Drawers](/cli/reference/drawers) — the Approval drawer in detail.
# Architecture (/cli/concepts/architecture)
Data flow in the CLI is one-directional:
```
transport → dispatcher → store → React (panels + drawers)
↑
└── commands flow back out via the dispatcher
```
The TUI consumes events and sends commands. Nothing else.
## What lives where [#what-lives-where]
| Layer | Responsibility |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Transport** | Speaks the wire protocol with Mogplex core: process spawn, daemon socket, or stdio JSONL. Emits structured events. Receives commands. |
| **Dispatcher** | Bridges transport ↔ store. Validates events with Zod schemas before they touch state. |
| **Store** | A single Zustand store holds all UI state — connection, active run, agents, timeline, MCP, memory, approvals, warnings, permissions. |
| **Reducer** | Pure transitions over events. New event in, new state out. |
| **React** | Panels and drawers subscribe to the store via selectors. Rendering is OpenTUI primitives — no DOM, no browser. |
| **Contracts** | Zod schemas + TypeScript types for every event, command, and state shape. The boundary with core. No React, no OpenTUI imports here. |
## Hard rules [#hard-rules]
These are invariants, not preferences:
* **Structured events only.** Stdout chunks are not the source of truth. Real protocol events flow through the transport as typed messages validated by Zod schemas in `contracts/`.
* **No polling.** Reducers, subscriptions, async iterables. No `setInterval` for status checks.
* **Single store.** Components subscribe via selectors. Don't keep parallel local state for things in the store.
* **One transport selector.** The router (`transport/router.ts`) is the only place that picks a transport — see [Transports](/cli/concepts/transports).
* **Approval-gated actions go through the approval system.** Drawers and panels never shortcut it.
* **Permissions hydrate from disk before any transport is selected.** So `/permissions ` takes effect on the next run without a restart.
## Why these rules matter [#why-these-rules-matter]
The CLI is supposed to be a credible operator surface for runs that may take minutes or hours and may touch a real workspace. That depends on the data model being honest:
* If the UI is event-driven, you can attach to a running session and rebuild the same screen.
* If state is centralized, the timeline, agents, and approvals can never disagree.
* If approvals are gated through one queue, "did I really approve this?" has a single answer.
## Read next [#read-next]
* [Transports](/cli/concepts/transports) — how core actually talks to the CLI.
* [Permissions](/cli/concepts/permissions) — what gets asked vs. allowed vs. denied.
* [Reference → Panels](/cli/reference/panels) — what each panel renders from the store.
# Attach (/cli/concepts/attach)
Attach mode lets you observe and steer a run that's already in flight. The CLI connects to the Mogplex daemon, replays the run's history into the local store, and then streams new events as they happen.
## Use it [#use-it]
```bash
mogplex --attach run_abc123
```
Or via env var (handy when the CLI is launched by another tool):
```bash
MOGPLEX_ATTACH_RUN_ID=run_abc123 mogplex
```
When `--attach` is set, the [transport router](/cli/concepts/transports) selects the **daemon** transport regardless of TTY state.
## What attach does [#what-attach-does]
1. Connects to the daemon socket (override with `MOGPLEX_DAEMON_SOCKET` if needed).
2. Asks for the run snapshot.
3. **Replays** the run's history into the store — agents, timeline, approvals, MCP, memory, cost are all rebuilt from events.
4. Subscribes to new events for the run.
You see the same cockpit you'd see if you'd started the run yourself.
## What you can do once attached [#what-you-can-do-once-attached]
Everything the cockpit normally does:
* Watch the agents and timeline live.
* Open diffs, memory, MCP, cost drawers.
* Approve or reject pending tool calls.
* Pause, resume, kill the run.
* Switch models with `/model`.
* Export the run with `/export`.
You're a real operator on the run, not a read-only observer.
## When to use it [#when-to-use-it]
* A run was started in CI or by a webhook and you need to take over.
* A teammate started a run on a shared daemon and you want to watch.
* Your previous CLI session crashed and you want to reattach to its run.
* The web app shows a long-running run and you want a richer terminal view.
## Auth and permissions [#auth-and-permissions]
Attach uses your local Mogplex token the same way as any other session. Permission mode is still respected — if you attach in `approval` mode and the run produces a gated action, the Approval drawer surfaces it for **you** to decide.
## Detach without killing the run [#detach-without-killing-the-run]
Quit the CLI normally (`/quit`, double-tap Ctrl+C). The run keeps going on the daemon. Reattach any time with the same `--attach `.
To **kill** the run, use `/kill` from inside the cockpit before detaching.
## Logout-then-attach [#logout-then-attach]
If you need to clear stored auth before reconnecting:
```bash
mogplex --attach run_abc123 --logout
```
That clears the Mogplex token (forces the login screen) and then proceeds to attach.
## Read next [#read-next]
* [Transports](/cli/concepts/transports) — how the daemon transport gets selected.
* [Reference → Export](/cli/reference/export) — turning an attached run into an artifact.
# Overview (/cli/concepts)
These pages explain the load-bearing concepts behind the CLI cockpit. Read them in order if you're new; jump to the one you need otherwise.
## Pick a page by question [#pick-a-page-by-question]
* "What actually happens when I press a key?" → [Architecture](/cli/concepts/architecture)
* "Why did the CLI pick this transport?" → [Transports](/cli/concepts/transports)
* "Why is this tool call asking me / why isn't it?" → [Permissions](/cli/concepts/permissions) and [Approvals](/cli/concepts/approvals)
* "How do I see a run that started in CI?" → [Attach](/cli/concepts/attach)
# Permissions (/cli/concepts/permissions)
The CLI's permission system has two halves:
1. A **mode** that sets the baseline: `approval` (default, asks before touching the workspace) or `auto` (run anything without asking).
2. **Rules** in config files that layer on top — `allow`, `deny`, and `ask` lists keyed by tool/command pattern.
## The two modes [#the-two-modes]
| Mode | Spawned runtime defaults | Use when |
| -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **`approval`** | sandbox `workspace-write`, approval policy `on-request` | You want gated workflows. Tool calls that touch the workspace pause and surface in the Approval drawer. |
| **`auto`** | sandbox `danger-full-access`, approval policy `never` | You explicitly want everything to run unattended. Use deliberately — there is no second prompt. |
Switch modes from the composer:
```text
/permissions approval
/permissions auto
```
The new mode applies on the next `/run` (the process transport reads permissions at spawn time — no restart needed).
## On-disk layout [#on-disk-layout]
Two files, in scope order. Both layer additively — see [How rules resolve](#how-rules-resolve) for what wins when they disagree.
```
~/.mogplex/permissions.json # global
~/.mogplex/projects//permissions.json # project-scoped (can only loosen)
```
Both follow the same shape:
```json
{
"version": 1,
"mode": "approval",
"rules": {
"allow": ["bash:git status", "bash:pnpm test"],
"deny": ["bash:rm -rf *"],
"ask": ["bash:gh pr merge*"]
}
}
```
* `version` must be `1`.
* `mode` is optional in project files — when absent, the project inherits the global mode (or the built-in default).
* `rules` are partial; missing lists default to empty.
Files are written with mode `0600` and the projects directory is `0700` so credentials and policy stay private.
## How rules resolve [#how-rules-resolve]
Each rule has one of three sources: `default`, `global`, or `project`. The resolver layers them like this:
1. **Built-in defaults** for the active mode.
2. **Global rules** from `~/.mogplex/permissions.json`.
3. **Project rules** from `~/.mogplex/projects//permissions.json`.
For each pattern, the most permissive level wins: `allow` beats `ask` beats `deny`. A `deny` only takes effect when no other layer (mode default, global, or project) marks the same pattern `allow` or `ask`. In other words, a layer can only **loosen** what an outer layer already restricts — it cannot tighten it.
**A project `deny` cannot override a global `allow`.** If `~/.mogplex/permissions.json` allows `bash:rm -rf *`, adding the same pattern to a project `deny` list will not block it. To restrict a pattern in a single repo, remove it from the global `allow` list and re-add it as `allow` only in the projects where it should run. This applies to mode defaults too: a global file cannot tighten what the active mode's built-in defaults already allow.
The slash status output (`/permissions`) explains why a pattern landed in `allow` vs `ask` vs `deny`, including which file it came from.
## Pattern format [#pattern-format]
Rules are matched against an action descriptor like `bash:`, `write:`, `read:`. Globs use shell-style wildcards. Concrete patterns:
| Pattern | Matches |
| ----------------- | ------------------------------ |
| `bash:git status` | exact command |
| `bash:pnpm test*` | command prefix |
| `write:src/**` | any write under `src/` |
| `read:.env*` | any read of dotenv-style files |
## Example: be permissive in a sandbox repo [#example-be-permissive-in-a-sandbox-repo]
```json
{
"version": 1,
"rules": {
"allow": ["bash:*", "write:**", "read:**"]
}
}
```
Drop that at `~/.mogplex/projects//permissions.json` to make a single repo run unattended while the global policy stays strict.
## What this does **not** control [#what-this-does-not-control]
* Auth (who you are signed in as) — see [Authentication](/cli/guides/authentication).
* MCP server enable/disable — see [Reference → Drawers](/cli/reference/drawers).
* Whether the CLI quits on Ctrl+C — see [Reference → Keybindings](/cli/reference/keybindings).
## Read next [#read-next]
* [Approvals](/cli/concepts/approvals) — how the queue surfaces gated calls.
* [Configuration and Flags](/cli/guides/configuration-and-flags) — env-var escape hatches.
# Transports (/cli/concepts/transports)
The CLI talks to Mogplex core over one of three transports. The router (`transport/router.ts`) is the **only** place that picks one.
## The three transports [#the-three-transports]
| Transport | When it's used | What it does |
| ----------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **process** | Default for an interactive terminal | Spawns a local exec runtime as a child process. The CLI watches its structured event stream and sends commands back. |
| **daemon** | Attach mode (`--attach`) or `MOGPLEX_TRANSPORT=daemon` | Connects to a running mogplex daemon over a Unix socket. Lets you observe and steer a run that is already in flight. |
| **stdio** | `MOGPLEX_TRANSPORT=stdio` or non-TTY stdin | Reads JSONL events from stdin and writes commands to stdout. Used for piping events from another process. |
## Selection rules [#selection-rules]
The router resolves the transport in this exact order:
1. `MOGPLEX_TRANSPORT=process` or `MOGPLEX_TRANSPORT=live` → **process**
2. `MOGPLEX_TRANSPORT=daemon` **or** `--attach ` is set → **daemon**
3. `MOGPLEX_TRANSPORT=stdio` **or** stdin is a pipe (non-TTY) → **stdio**
4. Default (TTY stdin, no attach) → **process**
If selection somehow falls through, the router falls back to **daemon** and emits a `transport_fallback` diagnostic.
## Examples [#examples]
```bash
# Default — spawn a local exec process
mogplex
# Attach to an in-flight run via the daemon socket
mogplex --attach run_abc123
# Force stdio (typically used by tooling, not humans)
echo '{"type":"snapshot",...}' | MOGPLEX_TRANSPORT=stdio mogplex
# Force the process transport even when stdin is a pipe
MOGPLEX_TRANSPORT=process mogplex
```
## Permissions and the process transport [#permissions-and-the-process-transport]
The process transport reads runtime permissions from the active mode **at spawn time**. That means `/permissions auto` (or `/permissions approval`) takes effect on the **next** `/run` without restarting the CLI. Same store, same transport — only the spawn flags change.
See [Permissions](/cli/concepts/permissions).
## Daemon socket location [#daemon-socket-location]
When using the daemon transport, the socket path is read from `MOGPLEX_DAEMON_SOCKET`. If unset, the daemon's default location is used.
## Why this matters [#why-this-matters]
Most users never think about transports. They matter when:
* You're debugging "why isn't my run showing up?" — usually the transport selection picked the wrong thing because `MOGPLEX_TRANSPORT` is set in the shell.
* You want to attach to a long-running CI run from your laptop — that's daemon mode.
* You're piping structured events from another tool into the cockpit — that's stdio.
For the env-var reference, see [Configuration and Flags](/cli/guides/configuration-and-flags).
# Authentication (/cli/guides/authentication)
The CLI ships to end users — auth is in-app. You do **not** need to set environment variables for normal use. Env vars exist as escape hatches for CI and ephemeral shells.
## Resolution order [#resolution-order]
When the CLI starts up, it resolves credentials in this order. The normal
customer path is account-backed login; provider env vars are compatibility and
development overrides.
1. **Auth env var in the current shell.** `MOGPLEX_API_KEY` and legacy local
provider env vars can override what is stored on disk.
2. **Stored credentials** in `~/.mogplex/auth.json` (mode `0600`). If you previously used Codex and have `CODEX_HOME` set, the CLI still honors it but it is deprecated — set `MOGPLEX_HOME` instead. See [Configuration and Flags → Storage](/cli/guides/configuration-and-flags#storage).
3. **No credentials** → the in-app **login screen** appears (or, in non-interactive contexts, a clear failure).
The practical rule: shell env vars outrank everything else.
## In-app login [#in-app-login]
On first run, use the Mogplex account path:
* **Sign in with Mogplex** — opens a browser flow for account-backed login. The CLI listens on a local callback and stores a Mogplex token. Recommended.
Account-backed login is the product path for normal use.
You can re-open the login screen later from the composer:
```text
/login
```
## What account-backed login means [#what-account-backed-login-means]
When you sign in with Mogplex, the CLI stores a `mogplex` credential in
`~/.mogplex/auth.json` and can reuse hosted state:
* synced model catalog
* remote MCP server definitions
* plan-backed model access configured for your Mogplex user
If account login succeeds but prompts fail, the hosted account usually does not
have usable model access yet. Check [Available Models](/web/models) and
[Plans & Billing](/plans-and-billing).
## Provider env vars [#provider-env-vars]
Direct provider environment variables are a compatibility and development
escape hatch, not the product setup path for billed Mogplex accounts. They
still take precedence over the account login path when they are present, so
unset them before debugging billed account behavior.
If both a stored credential and an env var exist for the same provider, the env
var wins.
## `/logout` [#logout]
```text
/logout
```
Clears the Mogplex token from `~/.mogplex/auth.json`. Three things to remember:
* **Env vars still win.** If the matching env var is set, the next session will still authenticate through it.
* **Restart for certainty.** The current process may still hold the old adapter. Quit (`/quit`) and relaunch if you need an immediate clean slate.
* **Logout clears hosted state.** Synced model catalog and remote MCP definitions vanish locally.
You can also force logout-then-attach in one shot:
```bash
mogplex --attach run_abc123 --logout
```
The CLI never reads `~/.mogplex/auth.json` to display secret material in
logs. Session logs at `~/.mogplex/logs/.jsonl` redact API keys,
tokens, and the raw contents of `auth.json`.
## Common outcomes [#common-outcomes]
* The login screen appears at startup → no Mogplex credential is available; sign in.
* Login succeeds but prompts fail → account login is active but the hosted account lacks model access. Check [Available Models](/web/models) and [Plans & Billing](/plans-and-billing).
* The CLI behaves differently than the in-app login implies → check env vars first; they outrank stored auth.
## See also [#see-also]
* [Configuration and Flags](/cli/guides/configuration-and-flags) — env-var escape hatches.
* [Concepts → Attach](/cli/concepts/attach) — `--logout` plus `--attach`.
* [Skills → mogplex-auth](/cli/skills/mogplex-auth) — the agent skill that gates other Mogplex actions on auth.
# Configuration and Flags (/cli/guides/configuration-and-flags)
The CLI is configured primarily in-app, with a small launcher flag surface,
environment-variable escape hatches, and advanced `config.toml` layers.
Env vars are not required for normal use. They exist for CI, attach
workflows, and tooling that needs to inject behavior. If you are setting
env vars to make day-to-day work happen, something is wrong — start with
the in-app login and `/permissions` instead.
## Launcher flags [#launcher-flags]
| Flag | What it does |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| `--attach ` | Attach to an in-flight run via the daemon transport. See [Concepts → Attach](/cli/concepts/attach). |
| `--logout` | Clear the stored Mogplex token before launching. Combine with `--attach` if needed. |
| `--events=jsonl` | Read events from stdin in JSONL format (used with stdio transport). |
Most day-to-day control still happens in-app through slash commands, drawers,
the login screen, model picker, and permissions picker.
## Environment variables [#environment-variables]
### Auth escape hatches [#auth-escape-hatches]
See the table in [Authentication → Resolution order](/cli/guides/authentication#resolution-order).
Provider env vars are compatibility and development escape hatches; normal
Mogplex usage should start with account-backed login.
### Transport selection [#transport-selection]
| Variable | Effect |
| ---------------------------------------- | --------------------------------------------------------- |
| `MOGPLEX_TRANSPORT=process` (or `=live`) | Force the process transport — spawn a local exec runtime. |
| `MOGPLEX_TRANSPORT=daemon` | Force the daemon transport — connect to a running daemon. |
| `MOGPLEX_TRANSPORT=stdio` | Force the stdio transport — read JSONL from stdin. |
| `MOGPLEX_DAEMON_SOCKET` | Override the daemon socket path. |
| `MOGPLEX_ATTACH_RUN_ID` | Equivalent to `--attach `. |
See [Concepts → Transports](/cli/concepts/transports) for the selection rules.
### Storage [#storage]
| Variable | Effect |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `MOGPLEX_HOME` | Override the home directory location (default `~/.mogplex/`). |
| `AGENTS_HOME` | Optional user command home. When set, slash-command discovery checks `$AGENTS_HOME/commands/` before `$MOGPLEX_HOME/commands/`. |
| `CODEX_HOME` | Deprecated fallback; use `MOGPLEX_HOME` instead. |
## `config.toml` [#configtoml]
Mogplex can read two TOML config layers:
| Path | Scope |
| --------------------------- | -------------------------------- |
| `$MOGPLEX_HOME/config.toml` | User-level advanced defaults. |
| `./.mogplex/config.toml` | Project-level advanced defaults. |
The runtime loader merges built-in defaults, user config, project config,
environment-derived values, and launcher overrides. In normal interactive use,
prefer the visible cockpit controls first:
* `/login` and the login screen for account credentials
* `/permissions` for permission mode
* `/model` for current model selection
* `/mcp` for MCP inspection and sync actions
Use `config.toml` when you need persistent advanced defaults that are not
better owned by the current session UI.
## Local state on disk [#local-state-on-disk]
| Path | Contents |
| -------------------------------------------------- | --------------------------------------------------------- |
| `~/.mogplex/auth.json` | Mogplex token and compatibility auth state (mode `0600`). |
| `~/.mogplex/config.toml` | User-level advanced config. |
| `~/.mogplex/permissions.json` | Global permission mode and rules. |
| `./.mogplex/config.toml` | Project-level advanced config. |
| `~/.mogplex/projects//permissions.json` | Per-project permission overrides. |
| `~/.mogplex/logs/.jsonl` | Structured session logs (secrets redacted). |
| `~/.mogplex/bin/mogplex` | The CLI binary (default install location). |
All Mogplex-owned files use restrictive modes (`0600` for files, `0700` for directories) so credentials and policy stay private.
## Configuring permissions [#configuring-permissions]
Permissions are managed by editing the JSON files above or by using `/permissions ` in the composer. See [Concepts → Permissions](/cli/concepts/permissions) for the on-disk schema and resolution rules.
## Configuring MCP [#configuring-mcp]
MCP servers are configured in [Web Settings](/web/settings) and synced to the
CLI when you are signed in to Mogplex. The CLI's MCP drawer surfaces what is
configured and supports sync or reauth actions.
Read [Connections and MCP](/configure-and-extend/connections-and-mcp) for the
full connection model.
## See also [#see-also]
* [Authentication](/cli/guides/authentication)
* [Concepts → Transports](/cli/concepts/transports)
* [Concepts → Permissions](/cli/concepts/permissions)
* [Connections and MCP](/configure-and-extend/connections-and-mcp)
# Overview (/cli/guides)
Use these pages when you want behavior and decision-making, not just syntax.
## Pick a guide by question [#pick-a-guide-by-question]
* "Why is the CLI choosing this auth state or model?" → [Authentication](/cli/guides/authentication)
* "Where does this default live and which env var overrides it?" → [Configuration and Flags](/cli/guides/configuration-and-flags)
* "How do I drive a run from the composer?" → [Slash Commands](/cli/guides/slash-commands)
* "How do I make Mogplex behave like part of this repo?" → [Project Commands](/cli/guides/project-commands)
## Read these in order if you are new [#read-these-in-order-if-you-are-new]
1. [Installation](/cli/installation)
2. [Quickstart](/cli/quickstart)
3. [Concepts → Architecture](/cli/concepts/architecture)
4. [Authentication](/cli/guides/authentication)
5. [Configuration and Flags](/cli/guides/configuration-and-flags)
6. [Slash Commands](/cli/guides/slash-commands)
7. [Project Commands](/cli/guides/project-commands)
# Project Commands (/cli/guides/project-commands)
Several repo-local layers shape how the CLI behaves inside a checked-out repo:
* `AGENTS.md` and `AGENTS.override.md` — durable instructions for any agent
operating in this codebase
* `agent.json` — structured project config for prompt suffix and related
project metadata
* `.agents/commands/**/*.md` — project-scoped custom command templates for
builds that expose custom command loading
* `~/.mogplex/projects//permissions.json` — per-project permission
overrides
All of these are optional. They make the experience better when the repo has
stable conventions, repeatable commands, or different gates than your global
default.
## `AGENTS.md` [#agentsmd]
`AGENTS.md` is the repo-local instruction layer. Place it at the project root,
or add narrower files in subdirectories when a monorepo package needs different
guidance.
Good content includes:
* project purpose and architecture notes
* build, test, lint, and typecheck commands
* layout and ownership conventions
* naming or error-handling patterns
* repo-specific guardrails the assistant should follow
Keep it durable. If guidance changes hourly, it belongs in the task prompt instead.
The CLI runtime reads discovered `AGENTS.md` fragments into the assembled
system prompt. It can also discover `$MOGPLEX_HOME/AGENTS.md` for user-level
guidance and `AGENTS.override.md` when a directory needs an explicit override.
For the full discovery model, see
[Repo Instructions](/configure-and-extend/repo-instructions).
## `agent.json` [#agentjson]
`agent.json` is a strict project-local JSON file. Use it sparingly for short
structured context such as a prompt suffix.
For behavior that has first-class controls, prefer the product surface that
owns it:
* model defaults in [Available Models](/web/models) or the CLI Model Picker
* tool policy in [Permissions](/cli/concepts/permissions)
* repeatable prompts in
[Custom Slash Commands](/configure-and-extend/custom-slash-commands)
## Project custom commands [#project-custom-commands]
Project commands live in:
```text
.agents/commands/**/*.md
```
They are the repo-local authoring format for reusable prompt templates.
Example:
```text
.agents/commands/review-staged.md -> /review-staged
.agents/commands/release/notes.md -> /release:notes
```
The legacy `.mogplex/commands/**/*.md` path is part of the loader's supported
discovery model, but `.agents/commands` is the preferred project path.
Before relying on a project command, confirm the running cockpit exposes it in
`/help`. Some current builds still expose only the built-in registry.
See [Custom Slash Commands](/configure-and-extend/custom-slash-commands).
## Per-project permissions [#per-project-permissions]
Permission rules can be set globally or per-project. The project file lives at:
```text
~/.mogplex/projects//permissions.json
```
It can override the mode and add `allow` / `deny` / `ask` rules that are layered **on top of** the global rules. Projects can only be **more permissive** than the global file — a project `deny` cannot tighten something the global file (or the mode default) already allows. See [Concepts → Permissions](/cli/concepts/permissions#how-rules-resolve) for the resolver rules.
Example — make a single sandbox repo run unattended while the global policy stays strict:
```json
{
"version": 1,
"rules": {
"allow": ["bash:*", "write:**", "read:**"]
}
}
```
See [Concepts → Permissions](/cli/concepts/permissions) for the schema, resolution rules, and how `/permissions` reports each rule's source.
## Verify what loaded [#verify-what-loaded]
In the composer:
```text
/permissions
```
Without an argument, `/permissions` shows the resolved mode and rules and explains where each pattern came from (`default`, `global`, or `project`).
## Recommended split [#recommended-split]
* put long-lived repo rules in `AGENTS.md`
* put repeatable prompt templates in `.agents/commands`
* put per-repo permission overrides in `~/.mogplex/projects//permissions.json`
* keep personal-only defaults in `~/.mogplex/permissions.json` (global)
* use `/permissions ` for one-off mode flips that don't deserve a config file
## Anti-patterns [#anti-patterns]
* putting volatile task notes in `AGENTS.md`
* putting secrets, tokens, or personal paths in project commands
* relying on a per-project `permissions.json` to **restrict** something the global already allows (the merge can only add allows; deny rules need to be set explicitly per scope)
* editing `permissions.json` while the cockpit is mid-run — wait until `/permissions` confirms the next state, then `/run` again
## See also [#see-also]
* [Repo Instructions](/configure-and-extend/repo-instructions)
* [Custom Slash Commands](/configure-and-extend/custom-slash-commands)
* [Concepts → Permissions](/cli/concepts/permissions)
* [Concepts → Approvals](/cli/concepts/approvals)
* [Configuration and Flags](/cli/guides/configuration-and-flags)
# Slash Commands (/cli/guides/slash-commands)
For the full list of slash commands, see [Commands](/cli/commands). This guide walks the workflows that actually use them.
## Start a run [#start-a-run]
```text
/run review the staged diff for regressions
```
The Agents panel populates as core spawns workers. The Timeline streams events. Watch the Header for `transport: nominal` and a non-empty `model`.
## Pause and resume [#pause-and-resume]
```text
/pause
/resume
```
`/pause` lets agents stop at the next safe point. Use it before you switch models or change permissions.
## Switch the model mid-run [#switch-the-model-mid-run]
```text
/model
```
Opens the **Model Picker** drawer. Pick a model and confirm. If the active permission mode gates `change_model` as `ask`, the change surfaces in the Approval drawer first.
## Inspect a diff [#inspect-a-diff]
```text
/diff
```
Opens the **Diff** drawer with the most recent patch. Step through hunks; approve or reject if the run is gated.
## Approve or reject pending tool calls [#approve-or-reject-pending-tool-calls]
The Approval drawer surfaces gated requests automatically. From the composer, you can also use the Command Palette:
```text
/help
```
Then search "Approval" to focus the drawer.
See [Concepts → Approvals](/cli/concepts/approvals).
## Switch permission modes [#switch-permission-modes]
```text
/permissions auto
/permissions approval
```
`auto` runs everything without asking; `approval` (the default) gates anything that touches the workspace. The change applies on the next `/run` — no restart required.
See [Concepts → Permissions](/cli/concepts/permissions).
## Check cost and usage [#check-cost-and-usage]
```text
/cost
```
Per-agent and per-run breakdown. Crossed thresholds also appear in the Priority alerts strip.
## Export the run [#export-the-run]
```text
/export
```
Opens the **Run Export** drawer. Pick a format (JSON, JSONL, Markdown) and scope.
See [Reference → Export](/cli/reference/export).
## Kill the run [#kill-the-run]
```text
/kill
```
Cancels the active run immediately. Agents are stopped; in-flight tool calls are interrupted.
## Quit the cockpit [#quit-the-cockpit]
```text
/quit
```
Or `/exit`, or double-tap `Ctrl+C` (single press is a soft-interrupt — see [Reference → Keybindings](/cli/reference/keybindings)).
## Common pitfalls [#common-pitfalls]
* **Typing `/run` with no arguments** — sends an empty task; you'll get an inline composer error.
* **Forgetting that `/permissions` is per-spawn** — you set the mode now; it applies to the next `/run`.
* **Using `q` with a drawer open** — `q` only quits when no drawer is open. While a drawer is open it's reserved for the drawer.
* **Pressing Ctrl+C once and walking away** — that's a soft-interrupt, not a quit. Press it twice within 1500ms to exit.
## Add your own commands [#add-your-own-commands]
Custom commands are markdown prompt templates from project or user scope. The
authoring format exists in the CLI runtime, but the running cockpit's active
registry is still whatever `/help` shows.
Use project commands for repo workflows:
```text
.agents/commands/review-staged.md
.agents/commands/release/notes.md
```
Use user commands for personal workflow shortcuts:
```text
$MOGPLEX_HOME/commands/debug-failing-test.md
```
See [Custom Slash Commands](/configure-and-extend/custom-slash-commands) for
frontmatter, arguments, aliases, template variables, precedence rules, and the
current registry limitation.
## See also [#see-also]
* [Commands](/cli/commands) — full slash command reference
* [Custom Slash Commands](/configure-and-extend/custom-slash-commands)
* [Reference → Keybindings](/cli/reference/keybindings)
* [Reference → Drawers](/cli/reference/drawers)
# Cost & Usage (/cli/reference/cost-and-usage)
The CLI tracks usage and cost as structured events flow in, then surfaces warnings when configured thresholds are crossed.
## Where you see it [#where-you-see-it]
| Surface | What it shows |
| ------------------------- | ----------------------------------------------------------------------------- |
| **Header** | The active model and (when available) abbreviated usage |
| **Cost drawer** (`/cost`) | Per-agent and per-run breakdown: input/output tokens, cost, projection, model |
| **Priority alerts strip** | Warnings for crossed thresholds and approaching run limits |
## What gets tracked [#what-gets-tracked]
* **Tokens** — input and output, per agent and per run.
* **Cost** — derived from token counts and the model's pricing where known.
* **Run limits** — configurable caps that, when crossed, can trigger a pause or warning depending on policy.
Numbers come from structured `usage_*` events emitted by core. The CLI does not estimate or extrapolate beyond what it's told.
## Thresholds and crossings [#thresholds-and-crossings]
Thresholds are evaluated against incoming usage events. Crossing a threshold is itself an event that:
* updates the Cost drawer
* adds a row to the Priority alerts strip
* surfaces in the Timeline
Typical thresholds:
| Type | Example |
| ------------ | --------------------------------------- |
| Soft warning | Approaching 80% of a run's token budget |
| Hard warning | Crossed the configured cost ceiling |
| Run limit | Maximum number of agent steps reached |
## What the cockpit does at a threshold [#what-the-cockpit-does-at-a-threshold]
By default, threshold crossings are informational — you see them, you decide. If your permission mode and rules are configured to gate on `run_command` or `change_model`, the agent's next action may also surface in the Approval drawer.
The cockpit never silently kills a run for crossing a soft threshold.
## Read next [#read-next]
* [Drawers](/cli/reference/drawers) — the Cost drawer
* [Concepts → Approvals](/cli/concepts/approvals) — gating on actions
* [Export](/cli/reference/export) — capture cost data with the run artifact
# Drawers (/cli/reference/drawers)
Drawers are modal overlays for deep views. Each one registers with the drawer registry at module load, so the [Command Palette](#command-palette) can list every drawer the build ships.
## Diff [#diff]
Shows the diff for a patch produced during a run. Opens with `/diff` or by selecting a patch event in the Timeline.
What you can do:
* step through hunks
* inspect the full file context
* approve / reject the patch (when permission mode requires it)
## Approval [#approval]
The pending-approval queue. Each item shows action, target, risk level, and the requesting agent. See [Concepts → Approvals](/cli/concepts/approvals) for how items get here.
What you can do:
* approve or reject inline
* batch-approve obviously related items
* jump to the related Timeline event
## MCP [#mcp]
Per-server view of every configured MCP server and its capabilities. Open with `/mcp` or via the MCP strip.
What you can do:
* inspect available tools per server
* see why a server is `unavailable` or `degraded`
* follow links into [Web Settings](/web/settings) for shared MCP configuration
## Memory [#memory]
Browse and manage memory entries. Open with `/memory`.
What you can do:
* read existing entries
* delete entries (gated by permission mode)
* see what was written during the active run
The CLI never mutates memory directly — every write goes through core and may surface in the Approval queue.
## Agent Detail [#agent-detail]
Focused view of one agent. Open by selecting an agent card and pressing enter.
What you can do:
* read the agent's current plan and recent actions
* inspect tool calls in flight
* soft-interrupt the agent (`Ctrl+C` while focused)
## Model Picker [#model-picker]
Switch the active run's model. Open with `/model`.
What you can do:
* pick from the synced model catalog (account-backed login) or local config
* preview pricing where available
* swap models mid-run (gated by permission mode if `change_model` is `ask`)
## Cost [#cost]
Per-run cost and token usage with thresholds and projections. Open with `/cost`. See [Cost & Usage](/cli/reference/cost-and-usage) for thresholds and warnings.
## Run Export [#run-export]
Serialize the current run for sharing or archival. Open with `/export`. See [Export](/cli/reference/export) for formats.
## Command Palette [#command-palette]
Fuzzy-find every action the cockpit exposes — slash commands, drawers, run controls, focus targets. Lists actions by category:
| Category | Examples |
| --------- | ----------------------------------------------------------------------------------------------------------------- |
| `command` | `/run`, `/pause`, `/diff`, `/mcp` |
| `drawer` | Open MCP, Open Diff, Open Memory, Open Agent Detail, Open Model Picker, Open Cost, Open Run Export, Open Approval |
| `control` | Pause Run, Resume Run, Cancel Run, Export Run |
| `focus` | Focus Agents, Focus Timeline, Focus Composer |
The Palette is the safety net when you don't remember a slash command name.
## Read next [#read-next]
* [Panels](/cli/reference/panels)
* [Commands](/cli/commands) — slash command reference
* [Concepts → Approvals](/cli/concepts/approvals)
# Export (/cli/reference/export)
Use `/export` to capture the active (or attached) run as a portable artifact. Opens the **Run Export** drawer with format and scope choices.
## What gets included [#what-gets-included]
* Run metadata: id, repo, branch, model, mode, start/end timestamps.
* Agents: roles, models, final status.
* Timeline: structured events (tool calls, patches, approvals, errors, lifecycle).
* Cost & usage: token counts and cost per agent.
* Approvals: every queued item with its decision.
* Memory writes performed during the run.
The export is built from the same store the cockpit renders from, so what you see in the panels is what lands in the artifact.
## Formats [#formats]
The Run Export drawer offers a small set of serializers:
| Format | Use when |
| ------------ | ------------------------------------------------------------------- |
| **JSON** | You want the structured data for tooling. One object per run. |
| **JSONL** | You want streaming events for replay or analysis. |
| **Markdown** | You want a human-readable summary suitable for PRs or post-mortems. |
Pick a scope — full run, timeline only, approvals only, etc. — before exporting.
## Where the file lands [#where-the-file-lands]
By default the artifact is written under the active run's local export directory. The drawer prints the resolved path on completion.
## When to export [#when-to-export]
* **Post-mortem** — capture a failed run for review.
* **Sharing** — send a teammate the markdown summary or the JSON for tooling.
* **Audit** — keep a record of every approval decision and tool call.
* **Resume context** — feed a JSONL export back into another tool that consumes Mogplex events.
## Detach without exporting [#detach-without-exporting]
Quitting (or killing the CLI process) does not auto-export. If you need the artifact, run `/export` first.
## Read next [#read-next]
* [Concepts → Attach](/cli/concepts/attach) — exporting works on attached runs too
* [Drawers](/cli/reference/drawers) — the Run Export drawer
# Overview (/cli/reference)
Use these pages when you know what you're looking at and need the specifics.
For slash commands, see [Commands](/cli/commands).
# Keybindings (/cli/reference/keybindings)
## Exit [#exit]
| Action | What happens |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **`Ctrl+C` (single press)** | Soft-interrupt — logs `[soft-interrupt]` to stderr. **Does not quit.** |
| **`Ctrl+C` twice within 1500ms** | Clean exit. Restores terminal state, stops the dispatcher, destroys the renderer. |
| **`q`** | Clean exit, but **only when no drawer or help overlay is open**. While a drawer is open, `q` is reserved for the drawer. |
| **`/quit` (alias `/exit`)** | Clean exit from the composer. |
The double-tap-to-exit rule prevents accidental quit-on-Ctrl+C while a long
run is in flight. Hitting Ctrl+C once is the conventional "soft cancel" —
hitting it twice means you really want out.
## Focus [#focus]
| Action | Key |
| ---------------------- | -------------------------------------------------------- |
| Focus the Agents panel | `focus:agents` (via Command Palette or palette shortcut) |
| Focus the Timeline | `focus:timeline` |
| Focus the Composer | `focus:composer` |
The exact shortcut keys are surfaced in the Command Palette (`/help` to open the palette and search "Focus").
## Drawer keys [#drawer-keys]
When a drawer is open:
| Key | Action |
| --------- | ----------------------------------------------- |
| `Esc` | Close the drawer |
| `↑` / `↓` | Move selection within the drawer |
| `Enter` | Activate the focused item (varies per drawer) |
| `a` | Approve (Approval drawer) |
| `r` | Reject (Approval drawer) |
| `q` | (reserved by the drawer; does not quit the app) |
Each drawer can register its own additional keymap. See the per-drawer entries in [Reference → Drawers](/cli/reference/drawers).
## Composer [#composer]
| Key | Action |
| ------------- | -------------------------- |
| `Enter` | Send |
| `Shift+Enter` | Newline |
| `Tab` | Autocomplete slash command |
| `↑` / `↓` | Browse composer history |
## Command Palette [#command-palette]
| Key | Action |
| ------------ | -------------------------------------------------------------- |
| Open palette | Listed in `/help`, also via the `Open Command Palette` action |
| Type | Fuzzy-search across commands, drawers, controls, focus targets |
| `Enter` | Run the selected action |
## Signals [#signals]
| Signal | Behavior |
| --------------------------- | -------------------------------------------------- |
| `SIGINT` (Ctrl+C) | Soft-interrupt then double-tap to exit (see above) |
| `SIGTERM` | Clean exit |
| crash / unhandled exception | Terminal state is restored on the way out |
The terminal is always restored on exit — cursor visible, raw mode off — even if the renderer crashed.
## Read next [#read-next]
* [Panels](/cli/reference/panels)
* [Drawers](/cli/reference/drawers)
* [Commands](/cli/commands)
# Panels (/cli/reference/panels)
The CLI lays out seven panels. Each one subscribes to the central store via selectors, so they can never disagree.
## Header [#header]
The status bar across the top.
| Field | Meaning |
| ----------------- | ------------------------------------------------------------------------------------------ |
| **repo / branch** | The active repository and branch |
| **model** | The model the active run is using |
| **mode** | Run mode (idle, planning, executing, etc.) |
| **run status** | ready, running, paused, completed, failed, killed |
| **dirty** | Whether the working tree has uncommitted changes |
| **perms** | Active permission mode (`approval` or `auto`) |
| **transport** | Connection health: `nominal` (connected), `connecting`, `reconnect`, `degraded`, `offline` |
The transport label uses aerospace-ops phrasing — `nominal` means everything is connected and healthy.
## Agents [#agents]
The left rail. Lists every agent on the active run as a card with:
* agent number
* name and role (architect, builder, reviewer, tester, researcher)
* model
* status (starting, planning, thinking, calling\_tool, editing, reviewing, testing, blocked, waiting\_for\_approval, paused, completed, failed, killed)
* current action (truncated to fit)
* an animated activity frame for actively-working agents
Below the agent cards, a **system status** block shows transport health, the active model, and MCP server counts.
Press the focus key (see [Keybindings](/cli/reference/keybindings)) to navigate; selecting an agent and pressing enter opens the **Agent Detail** drawer.
## Timeline [#timeline]
The center panel. Streams structured events as they happen — tool calls, patches, approvals, errors, model routing decisions, run lifecycle. Events are typed (validated by Zod schemas in `contracts/`), not parsed stdout.
Use it to:
* watch what an agent is actually doing
* find the event that triggered an approval or an error
* scroll back through the run's history
## Context & Memory [#context--memory]
What's loaded in context and what's been written to memory. Subscribes to memory events from core. Open the **Memory** drawer (`/memory`) to manage entries.
## MCP strip [#mcp-strip]
A compact status row of configured MCP servers and their readiness. Open the **MCP** drawer (`/mcp`) for the full per-server view.
## Command input [#command-input]
The composer at the bottom. Type:
* a freeform task — sends to the active agent
* `/` — runs a slash command (see [Commands](/cli/commands))
* partial slash — autocomplete candidates appear above the line
Unknown slash commands surface as inline composer errors so you don't accidentally send them as prompts.
## Priority alerts [#priority-alerts]
A strip that surfaces things you should not miss even if a drawer is closed:
* high-risk pending approvals
* usage / cost threshold crossings
* run limits about to be hit
* transport degradation or reconnect events
Alerts auto-dismiss when the underlying condition clears.
## Read next [#read-next]
* [Drawers](/cli/reference/drawers)
* [Keybindings](/cli/reference/keybindings)
* [Concepts → Architecture](/cli/concepts/architecture)
# Skills (/cli/skills)
Mogplex ships a set of [Anthropic Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) that teach a skill-aware agent how to help users drive the Mogplex CLI.
The current CLI is interactive-only — there is no headless `exec` surface
for an agent to call. These skills are **guidance skills**: they teach an
agent to recommend the right slash command, walk a user through the login
screen, and help author repo-local config (`AGENTS.md`,
`permissions.json`). Agents do not drive the cockpit directly.
## Source of truth [#source-of-truth]
The canonical skill files live at `skills//SKILL.md` in [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs). The pages under this section mirror those files.
## Skills [#skills]
## Install [#install]
The skill files are hosted at [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs) under `skills/`. Pick one fetch method, then copy into your agent host.
### Claude Code [#claude-code]
```bash
# Option A — full clone
git clone https://github.com/webrenew/mogplex-docs.git
SKILLS=mogplex-docs/skills
# Option B — sparse download of just the skills/ tree
npx -y degit webrenew/mogplex-docs/skills mogplex-skills
SKILLS=mogplex-skills
```
Then:
```bash
# Global
mkdir -p ~/.claude/skills && cp -R "$SKILLS"/* ~/.claude/skills/
# Or per-project
mkdir -p .claude/skills && cp -R "$SKILLS"/* .claude/skills/
```
### Claude Agent SDK [#claude-agent-sdk]
Skills picked up automatically via `settingSources: ["user", "project"]`:
```ts
import { query } from "@anthropic-ai/claude-agent-sdk";
const response = query({
prompt: "How do I switch models in Mogplex?",
options: { settingSources: ["user", "project"] },
});
```
### Cursor / opencode / other hosts [#cursor--opencode--other-hosts]
Copy the body of each `SKILL.md` into the host's project-rules or system-prompt-include mechanism. The frontmatter is Claude Code / Agent SDK-specific; the markdown body is portable.
## Design principles [#design-principles]
* **Guidance, not execution.** Skills tell the user what to do in the cockpit. They do not try to drive the TUI.
* **Auth handoff.** Auth lives in the cockpit's login screen. Skills recommend `/login` and explain env-var precedence.
* **Repo-local config is fair game.** Skills can help the user author `AGENTS.md` and `~/.mogplex/projects//permissions.json` — those are plain files.
* **No silent writes.** Anything that mutates user-owned state is recommended to the user, not done by the agent.
# mogplex-auth (/cli/skills/mogplex-auth)
This page mirrors the canonical `SKILL.md` at [`skills/mogplex-auth/SKILL.md`](https://github.com/webrenew/mogplex-docs/blob/main/skills/mogplex-auth/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths).
## Frontmatter [#frontmatter]
```yaml
name: mogplex-auth
description: Guides the user through the Mogplex CLI's in-app login flow, credential precedence, and troubleshooting. Use when the user asks to sign in, switch accounts, debug env-var overrides, or when a Mogplex command fails with an auth error.
```
## Body [#body]
The Mogplex CLI authenticates **in-app**. There is no `mogplex login status` subcommand; the cockpit's login screen is the only flow. Use this skill to advise the user — you cannot inspect or change credentials from outside the cockpit.
## Resolution order [#resolution-order]
The cockpit picks credentials in a fixed order:
1. **Auth env var in the current shell.** `MOGPLEX_API_KEY` and legacy local
provider env vars can override what is stored on disk.
2. **Stored credentials** in `~/.mogplex/auth.json` (mode `0600`).
3. **No credentials** → the cockpit's in-app login screen appears.
Env vars beat stored creds. Always.
## Establish auth [#establish-auth]
### Preferred: account-backed browser login [#preferred-account-backed-browser-login]
Tell the user to launch the cockpit and pick **Sign in with Mogplex** on the login screen, or type `/login` from the composer in an open cockpit.
```bash
mogplex
# pick "Sign in with Mogplex" on the login screen
```
A browser flow opens; the cockpit listens on a local callback and stores the token in `~/.mogplex/auth.json`. The user does the click-through; you do not drive the browser.
Account-backed login unlocks synced model catalog, remote MCP server
definitions, and plan-backed hosted model access.
### Compatibility: provider env var [#compatibility-provider-env-var]
Provider env vars are compatibility and development escape hatches. They are
not the normal customer setup path for billed Mogplex accounts.
Do not write keys into shell rc files on the user's behalf. If a user is
explicitly working in a development or compatibility flow, describe the env-var
override and let them set it themselves.
## Sanity-check env vars (advisory) [#sanity-check-env-vars-advisory]
You can sanity-check which env vars are set without printing values:
```bash
env | grep -E '^(MOGPLEX|ANTHROPIC|OPENAI|GOOGLE_GENERATIVE_AI|GROQ|MISTRAL|DEEPSEEK|XAI|COHERE|VERCEL)_' | sed 's/=.*/=/'
```
Never echo a raw key.
## Troubleshooting [#troubleshooting]
| Symptom | What to recommend |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Login screen appears at every launch | No credential stored and no env var set. Pick a path on the login screen. |
| Login succeeds but prompts fail with "no model access" | Account-backed login is active but the hosted account lacks model access. Direct the user to [Available Models](https://www.mogplex.com/web/models) and [Plans & Billing](https://www.mogplex.com/plans-and-billing). |
| Cockpit behaves differently than expected after `/login` | An env var is overriding the stored credential. Have the user `unset` it and relaunch. |
| User wants to switch accounts | Type `/logout` in the composer, then `/login` (or relaunch). |
## Sign out [#sign-out]
```text
/logout # type in the composer
```
Or, before attaching to a run:
```bash
mogplex --attach run_abc123 --logout
```
Three things to remember:
* **Env vars still win** on the next session.
* **Restart for certainty.** The current process may still hold the old adapter.
* **Logout clears hosted state.** Synced model catalog and remote MCP definitions vanish locally.
Always confirm with the user before suggesting `/logout`.
## Hard rules [#hard-rules]
* Never read or modify `~/.mogplex/auth.json` directly.
* Never echo a raw key, even from env. Redact.
* Never write a key into a shell config file without explicit user consent.
* Never advise the user to put a key into a JSON config for another agent host when the in-app login would give them an account-backed token instead.
## See also [#see-also]
* [using-mogplex-cli](/cli/skills/using-mogplex-cli)
* [Authentication guide](/cli/guides/authentication)
* [Configuration and Flags](/cli/guides/configuration-and-flags)
# mogplex-slash (/cli/skills/mogplex-slash)
This page mirrors the canonical `SKILL.md` at [`skills/mogplex-slash/SKILL.md`](https://github.com/webrenew/mogplex-docs/blob/main/skills/mogplex-slash/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths).
## Frontmatter [#frontmatter]
```yaml
name: mogplex-slash
description: Recommends the right Mogplex slash command for a user's intent and explains what each command does in the cockpit composer. Use when the user asks how to start, pause, kill, or control a Mogplex run, attach to one from CI, switch models, manage approvals, or export.
```
## Body [#body]
The Mogplex CLI's command surface is **slash commands** in the cockpit composer. They run inside the interactive TUI — not from the shell. Use this skill to tell the user which slash command to type.
### Run control [#run-control]
| Intent | Slash command |
| --------------------- | ------------- |
| Start a new run | `/run ` |
| Pause the active run | `/pause` |
| Resume a paused run | `/resume` |
| Cancel the active run | `/kill` |
### Surface inspection (open a drawer) [#surface-inspection-open-a-drawer]
| Intent | Slash command |
| ----------------------------- | ------------- |
| List agents on the active run | `/agents` |
| Per-MCP-server status | `/mcp` |
| Browse memory | `/memory` |
| Inspect a patch | `/diff` |
| Tokens, cost, projection | `/cost` |
### Cockpit control [#cockpit-control]
| Intent | Slash command |
| ---------------------------------- | ------------------------------- |
| Switch models mid-run | `/model` |
| Set permission mode | `/permissions ` |
| Show the resolved permission state | `/permissions` (no arg) |
| Serialize the run | `/export` |
| Open the command palette | `/help` |
| Clear the composer | `/clear` |
| Quit the cockpit | `/quit` (alias `/exit`) |
### Auth [#auth]
| Intent | Slash command |
| -------------------------- | ------------- |
| Open the in-app login flow | `/login` |
| Clear stored credentials | `/logout` |
### When the user says… [#when-the-user-says]
| User says | You recommend |
| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
| "Run a task on this repo" | Open `mogplex` and type `/run ` |
| "Pull up that run from CI" | `mogplex --attach ` |
| "Switch to Sonnet" | Type `/model` in the composer |
| "Approve all pending tool calls" | Open the Approval drawer (use Command Palette via `/help` if not visible) and approve from there |
| "Run unattended for the next hour" | `/permissions auto` — flag the safety implications |
| "Save what just happened" | `/export` and pick Markdown for human-readable, JSON/JSONL for tooling |
| "Get out" | Double-tap Ctrl+C within 1500ms, or `/quit` |
### What you cannot do [#what-you-cannot-do]
* Run a slash command from the shell. There is no `mogplex slash` subcommand; slash commands only execute inside the running cockpit.
* See which slash commands are available without launching the cockpit. The registry is built into the binary; `/help` inside the cockpit shows the live list.
* Drive the cockpit on the user's behalf. Tell them what to type.
### Safety [#safety]
* `/permissions auto` is the explicit user opt-in to "no questions asked." Recommend `/permissions approval` (the default) for normal use.
* `/kill` cancels the active run immediately and interrupts in-flight tool calls. Confirm before suggesting it on a long run.
* `/logout` clears stored credentials including hosted Mogplex state (synced model catalog, remote MCP). Confirm before suggesting.
## See also [#see-also]
* [using-mogplex-cli](/cli/skills/using-mogplex-cli)
* [mogplex-auth](/cli/skills/mogplex-auth)
* [Commands](/cli/commands)
# using-mogplex-cli (/cli/skills/using-mogplex-cli)
This page mirrors the canonical `SKILL.md` at [`skills/using-mogplex-cli/SKILL.md`](https://github.com/webrenew/mogplex-docs/blob/main/skills/using-mogplex-cli/SKILL.md). Copy that file into your agent host (see [Skills overview](/cli/skills) for install paths).
## Frontmatter [#frontmatter]
```yaml
name: using-mogplex-cli
description: Umbrella skill for guiding a user through the Mogplex CLI cockpit when no Mogplex MCP server is available. Use when the user asks how to start a run, attach to a run, switch models, manage approvals, or configure permissions in the Mogplex CLI. Also triggers on mentions of "mogplex", "AGENTS.md", or "~/.mogplex/".
```
## Body [#body]
The Mogplex CLI ships two surfaces in one binary: an interactive cockpit (the TUI) and a [headless subcommand surface](/cli/automation) (`mogplex run`, `mogplex runs events`, etc.) for scripts and CI. Agents cannot drive the TUI itself, but they can shell out to the headless commands. Use this skill to **advise** the user on which to use, what to type in the composer when they're in the cockpit, and what to put in repo-local config files.
### When to use this skill [#when-to-use-this-skill]
* The user references their Mogplex account, runs, agents, MCP, memory, approvals, or cost.
* The user asks how to do something in the Mogplex cockpit.
* The user wants to author `AGENTS.md` or per-project `permissions.json`.
### Preflight [#preflight]
Confirm the CLI is installed before recommending it:
```bash
command -v mogplex >/dev/null 2>&1 || { echo "mogplex CLI not installed" >&2; exit 1; }
```
The `exit 1` matters: skill-aware hosts gate on the exit code, so a missing binary must fail the preflight rather than silently passing. If it's missing, point the user at [Installation](https://www.mogplex.com/cli/installation).
You **cannot** check auth state from outside the cockpit — there is no `mogplex login status` subcommand. Tell the user that the cockpit will surface the login screen on first launch if no credential is stored.
### Core guidance map [#core-guidance-map]
| Intent | What to tell the user |
| ----------------------------------- | --------------------------------------------------------------------------------------- |
| Start a run | Launch `mogplex`, then type `/run ` in the composer. |
| Attach to an in-flight run | `mogplex --attach ` — see [Attach](https://www.mogplex.com/cli/concepts/attach). |
| Switch models | Type `/model` in the composer to open the Model Picker drawer. |
| Approve / reject pending tool calls | The Approval drawer surfaces them automatically; the user clicks Approve or Reject. |
| Switch permission modes | Type `/permissions auto` or `/permissions approval` in the composer. |
| Inspect cost | Type `/cost` to open the Cost drawer. |
| Export the run | Type `/export` to open the Run Export drawer. |
| Quit | Type `/quit`, or double-tap Ctrl+C within 1500ms. |
For the full slash list see [Commands](https://www.mogplex.com/cli/commands).
### Decision flow [#decision-flow]
```
user wants Mogplex action
│
▼
is the cockpit already open in the user's terminal?
│
no ──► tell them to run `mogplex` (or `mogplex --attach `)
yes
│
▼
is it a slash command? ── yes ──► tell user to type "/" in the composer
│
no
▼
is it a config / file change?
│
yes ──► help them author the file (AGENTS.md, permissions.json)
no ──► describe the workflow in the cockpit (panels, drawers)
```
### What you cannot do [#what-you-cannot-do]
* Drive the **TUI** from a script. The cockpit is interactive-only. (For headless work, use `mogplex run` / `mogplex runs events --follow` — see [Automation](/cli/automation).)
* Read auth state from outside the cockpit. There is no `login status` subcommand; only the cockpit knows.
* Mutate `~/.mogplex/auth.json` directly. Tell the user to use `/login` or `/logout` in the cockpit.
* Run a slash command headlessly. Slash commands only execute inside the running cockpit — the equivalent for scripts is the `mogplex ` surface.
### What you **can** do [#what-you-can-do]
* Author `AGENTS.md` at the repo root with stable repo guidance (build commands, conventions, layout).
* Author `~/.mogplex/projects//permissions.json` with `allow` / `deny` / `ask` rules — see [Permissions](https://www.mogplex.com/cli/concepts/permissions) for the schema.
* Recommend env-var escape hatches (`MOGPLEX_TRANSPORT`, `MOGPLEX_ATTACH_RUN_ID`) only when they fit CI, attach, or development workflows — see [Configuration and Flags](https://www.mogplex.com/cli/guides/configuration-and-flags).
### Safety [#safety]
* Confirm with the user before authoring or modifying any file under `~/.mogplex/` — those affect every Mogplex run on the machine.
* Never write a key into a shell rc file on the user's behalf.
* Recommend `/permissions approval` (the default) over `/permissions auto` unless the user explicitly opts into unattended runs.
## See also [#see-also]
* [mogplex-slash](/cli/skills/mogplex-slash) — recommending slash commands
* [mogplex-auth](/cli/skills/mogplex-auth) — guiding the login flow
* [Slash Commands guide](/cli/guides/slash-commands)
# Overview (/web/agents)
The Agents area is the reusable behavior layer for Mogplex.
The top-level `/agents` route redirects to `/agents/roster`, and the product
sub-nav is split into:
* `/agents/roster`
* `/agents/skills`
* `/agents/rules`
* `/agents/context`
## What lives here [#what-lives-here]
* **Roster** for built-in agents, custom agents, preset forks, model selection,
categories, and prompt editing
* **Skills** for reusable workflow or capability packages
* **Rules** for shared instruction blocks and policy constraints
* **Context** for reusable memory and background knowledge
This area defines the reusable ingredients. Other surfaces bind those agents to
repos, events, or workflow graphs later.
## What the roster actually does [#what-the-roster-actually-does]
The roster is not just a static list of prompts.
It merges:
* built-in preset agents
* your owned custom agents
* forks of presets you have customized
From there you can:
* create a new custom agent
* fork a preset and customize it without mutating the original preset
* edit name, description, model, category, and system prompt
* search across the roster by name or description
* group agents into built-in or custom categories
* create and delete custom categories
* replace agents pinned to hidden legacy models with visible models from your
enabled catalog
Some other product surfaces can also create owned forks behind the scenes. For
example, assigning a built-in preset agent to repo-bound work can resolve to an
owned fork so that the routing layer points at a real agent record in your
account.
## Categories and model availability [#categories-and-model-availability]
Two product behaviors are easy to miss:
* Categories are validated. Custom agents can be forced into a real category,
and deleting a category moves those agents into a "needs category" state.
* Model choice is constrained by your enabled model catalog. An agent can still
exist on a hidden legacy model, but future edits should generally move it to a
visible model.
That means the roster is both an authoring surface and a hygiene surface for
long-lived agents.
## Slugs and mention routing [#slugs-and-mention-routing]
For GitHub mentions, Mogplex routes against the agent slug, not the display
name.
That means:
* `@mogplex` uses whichever mention route is marked default
* `@mogplex/` targets a specific agent route by slug
Examples:
* `@mogplex/triage`
* `@mogplex/frontend-review`
* `@mogplex/ci-fixer`
The slug is the durable handle when you wire mention-based
[Triggers](/web/triggers) or mention-entry [Automations](/web/automations).
Keep it short, lowercase, and predictable from the job the agent does.
## Skills, rules, and context are separate on purpose [#skills-rules-and-context-are-separate-on-purpose]
The non-roster tabs exist because Mogplex treats reusable behavior as more than
just a system prompt.
* **Skills** hold reusable procedures, tools, prompts, and workflows.
* **Rules** hold account-level instruction files shared across agents.
* **Context** holds reusable memory and background knowledge.
That split lets you keep the reusable agent definition stable while still
evolving the shared knowledge it depends on.
## How Agents relates to the rest of the product [#how-agents-relates-to-the-rest-of-the-product]
Think of the reusable agent definition as the base layer:
* define the reusable behavior in **Agents**
* bind it to a repo in [Assignments](/web/assignments)
* bind it to GitHub events in [Triggers](/web/triggers)
* orchestrate multiple steps around it in [Automations](/web/automations)
Flow nodes inside Automations can still override parts of the reusable
definition, such as model choice, role, step count, or timeout, without
rewriting the master agent.
## Start here when [#start-here-when]
* you need a reusable agent before wiring routing
* you want to fork a preset instead of building from scratch
* mention routing needs a predictable slug
* several repos or automations should share the same core behavior
* model or category hygiene has drifted and you want to clean it up centrally
## In this section [#in-this-section]
* [Roster and Slugs](/web/agents/roster-and-slugs) for agent identity, presets,
forks, and mention handles
* [Skills, Rules, and Context](/web/agents/skills-rules-context) for the shared
libraries that shape agent behavior
If you already know the repo and just need to attach recurring work, start from
[Projects](/web/spaces), [Assignments](/web/assignments), or
[Triggers](/web/triggers) instead.
# Roster and Slugs (/web/agents/roster-and-slugs)
The roster is where Mogplex stores reusable agent definitions.
Those definitions are then referenced by [Triggers](/web/triggers),
[Assignments](/web/assignments), and [Automations](/web/automations).
Think of the roster as the durable identity layer for agents, not just a place
to keep prompt snippets.
## What actually lives in the roster [#what-actually-lives-in-the-roster]
The current roster mixes a few different kinds of agent entries:
* **Default** preset agents that ship with Mogplex
* **Customized** forks of those presets
* fully **Custom** agents you create yourself
That distinction matters because the editor treats them differently:
* preset agents are reusable defaults
* presets can be customized without mutating the shipped version
* custom and customized agents can be edited or deleted directly
In practice, this gives you a safe path:
1. start from a preset if one is close
2. fork it when you need your own version
3. keep the fork as the repo or team-specific identity you actually route to
## What fields matter operationally [#what-fields-matter-operationally]
The fields that matter most in the current editor are:
* **Name** for humans scanning the roster
* **Description** for selection and search
* **Category** for grouping and navigation
* **Model** for capability, cost, and latency behavior
* **System prompt** for the durable behavior contract
* **Slug** for targeted GitHub mention routing
Slug is mostly routing metadata rather than the main thing you manage in the
roster editor day to day, but it still matters when GitHub mentions need to
resolve to a specific agent.
Two validation details are worth knowing:
* category is required when creating or saving an agent
* the editor only lets you pick from enabled models, even though older agents
can still carry legacy model ids
## Presets, customizations, and legacy models [#presets-customizations-and-legacy-models]
The roster UI exposes a few badges that reflect real product state:
* **Default** means a preset with no fork yet
* **Has customization** means a preset already has a forked version
* **Custom** means a user-created agent
* **Customized** means a fork of a preset
* **Needs category** means the agent no longer maps cleanly to a current
category
* **Legacy model** means the agent still points at a hidden or stale model id
Legacy models are especially important operationally.
Mogplex can still load an older agent that references a hidden model, but the
editor treats that as something you should replace rather than keep building on.
## Categories are not cosmetic [#categories-are-not-cosmetic]
Categories are part of how the roster stays usable once you have more than a
few agents.
The roster supports:
* built-in categories such as Next.js, Performance, API, Security, Frontend,
and PR Review
* custom categories you create yourself
* search across names and descriptions
* a **Needs Category** bucket for custom agents that no longer map to a current
category
Deleting a custom category does not delete the agents using it. Those agents
fall back into **Needs Category** so you can reassign them cleanly.
## Where slugs matter [#where-slugs-matter]
If you only remember one thing, remember this:
GitHub mention routing uses the agent slug, not the display name.
That means:
* `@mogplex` targets the default mention route
* `@mogplex/` targets a specific route by slug
Examples:
* `@mogplex/triage`
* `@mogplex/frontend-review`
* `@mogplex/ci-fixer`
## Triggers vs Automations [#triggers-vs-automations]
Slugs matter in both routing surfaces, but not in exactly the same way.
### Triggers [#triggers]
For mention [Triggers](/web/triggers), Mogplex will backfill a missing slug
from the agent name when you bind the trigger.
That makes trigger-based targeted mention routing a little more forgiving than
it looks at first glance.
### Automations [#automations]
For mention-entry [Automations](/web/automations), Mogplex routes targeted
mentions against the slug on an **entry agent** connected directly to the start
node.
If that entry agent has no slug, targeted mention routing has nothing stable to
match against.
In practice:
* mention automations should use entry agents with clear slugs
* downstream agents do not control mention matching
* default mention automations are safer than targeted ones when your roster is
still being cleaned up
## Slug hygiene [#slug-hygiene]
A good slug is:
* short
* lowercase
* easy to predict
* tied to the job, not a temporary initiative
Prefer:
* `triage`
* `security-review`
* `bundle-size`
* `release-manager`
Avoid:
* sentence-like slugs
* unstable slugs tied to one sprint or experiment
* ambiguous names like `agent-2`
## Base agent vs flow override [#base-agent-vs-flow-override]
This is the other common confusion point.
The roster entry is the reusable identity.
An automation node can still override:
* model
* system prompt
* timeout
* max steps
That override changes the behavior of that node only. It does not mutate the
base agent the rest of the product sees.
## Rule of thumb [#rule-of-thumb]
Use the roster to define stable reusable identities.
Use categories to keep those identities navigable.
Use slugs when you want humans to be able to call those identities directly
from GitHub.
# Skills, Rules, and Context (/web/agents/skills-rules-context)
Mogplex splits shared agent building blocks into three different libraries on
purpose:
* skills
* rules
* context
They are related, but they are not interchangeable.
## Skills [#skills]
Skills are reusable capability packages.
Use them when an agent should know **how to do a class of work**, such as:
* following a specialist workflow
* using a reusable investigation pattern
* applying a repeatable framework-specific playbook
* importing an external skill from a registry
In the current product, the Skills surface has three acquisition paths:
* **local skills** you create and edit directly
* **skills.sh registry** browsing and install
* **Vercel docs** import, which can turn a Vercel document into a local skill
Local skills are typed as:
* runbook
* tool
* prompt
* workflow
That makes the Skills area both a library editor and a discovery surface.
## Rules [#rules]
Rules are shared instruction blocks and policy constraints.
Use them when an agent should consistently respect **how it is allowed to
operate**, such as:
* coding standards
* repo guardrails
* deployment restrictions
* review style
* behavioral policy
The current Rules surface is a small global file manager. You can create, edit,
and delete shared rule files, then reuse them across many agents instead of
copying the same policy into every system prompt.
## Context [#context]
Context is reusable reference material and memory.
Use it when an agent needs **background knowledge** repeatedly, such as:
* architecture notes
* domain terminology
* system boundaries
* durable preferences
* timeline events worth remembering
The current Context surface is memory-oriented, not just a static text list.
It supports four lanes:
* **Session** for the current working set
* **Semantic** for durable truths and preferences
* **Episodic** for timeline events and milestones
* **Procedural** for reusable workflows and runbooks
You can add entries, search them, delete them, and run **Compact** or
**Checkpoint** actions. Context can also be scoped to the current repo or
workspace session when that information is available.
## How to split responsibility [#how-to-split-responsibility]
Use this decision rule:
* if it teaches a repeatable workflow or specialty: **skill**
* if it constrains behavior or policy: **rule**
* if it explains the system or preserves useful memory: **context**
When those are separated cleanly, agent prompts stay smaller, more reusable,
and easier to maintain.
## Why this matters in practice [#why-this-matters-in-practice]
Without this split, teams tend to create one giant agent prompt that mixes:
* capabilities
* policies
* architecture notes
* temporary instructions
* memory that should have been stored elsewhere
That works briefly and then becomes difficult to reason about or update.
Mogplex works better when the roster entry stays readable and these supporting
libraries hold the reusable detail.
## A good composition pattern [#a-good-composition-pattern]
For a strong reusable agent:
1. define the core identity in the roster
2. attach shared rules for non-negotiable behavior
3. add skills for specialist workflows
4. use context for background knowledge or memory the task actually needs
That gives you a stable reusable agent without turning every task into prompt
surgery.
# Authentication (/web/api/authentication)
The hosted Mogplex API is shared by the web app, the CLI, and internal test
workflows.
That means auth is resolved in priority order instead of assuming every caller
is a browser.
## Auth resolution order [#auth-resolution-order]
The common control-plane helper resolves in this order:
1. `Authorization: Bearer mog_...` personal access token (PAT)
2. internal Playwright auth headers used in end-to-end testing
3. browser session auth from the signed-in web app
The public `/api/v1/mogplex/*` surface accepts **only** PATs — the Playwright
and session paths are for internal callers. Use a PAT for anything outside the
browser.
## Personal access tokens [#personal-access-tokens]
PATs use the `mog_` bearer format: `mog_` prefix followed by 32 base62
characters. They are stored as a SHA-256 hash; the plaintext value is shown to
you exactly once at creation time.
### Issuing a PAT [#issuing-a-pat]
Through the web UI:
1. Sign in at [mogplex.com](https://www.mogplex.com).
2. Go to **Settings → API Keys**.
3. Click **Create token**, give it a name, pick scopes and (optionally) an expiry, and copy the plaintext value.
Through the management API (this endpoint requires browser-session auth — PATs
can't issue other PATs):
```bash
curl -sS \
-X POST \
--cookie "$YOUR_SESSION_COOKIE" \
-H "Content-Type: application/json" \
-d '{"name":"laptop CLI","scopes":["read","write"],"expiresInDays":90}' \
"$MOGPLEX_BASE_URL/api/settings/api-keys"
```
Response (the plaintext `token` field is returned once):
```json
{
"id": "key-uuid",
"token": "mog_AbCdEf1234567890aBcDeF1234567890aB",
"prefix": "mog_AbCdEf12",
"scopes": ["read", "write"],
"expiresAt": "2026-08-15T00:00:00.000Z"
}
```
The plaintext token is shown only at creation. The server stores a SHA-256
hash and the first 12 characters as a display prefix — neither can be reversed.
If you lose the token, revoke the row and create a new one.
### Revoking a PAT [#revoking-a-pat]
```bash
curl -sS \
-X DELETE \
--cookie "$YOUR_SESSION_COOKIE" \
"$MOGPLEX_BASE_URL/api/settings/api-keys/{id}"
```
Revocation sets `revoked_at` on the row. The next request that uses the
revoked token returns `UNAUTHORIZED` (401) — there is no grace period.
### Expiry [#expiry]
If a token has `expiresAt`, requests after that timestamp return
`UNAUTHORIZED` (401). The CLI does not refresh tokens automatically; issue a
new one when an old one nears expiry.
## Scopes [#scopes]
Two scopes exist today:
| Scope | Grants |
| ------- | ------------------------------------------------------------------------------------------ |
| `read` | All `GET /api/v1/mogplex/*` endpoints (repos, sandboxes, runs, run events) |
| `write` | Mutating endpoints: `POST /runs`, `POST /runs/{id}/cancel`, future sandbox lifecycle POSTs |
Tokens default to `["read", "write"]` unless you explicitly request a smaller
set. Tokens issued before scope enforcement landed were backfilled to
`["read", "write"]` so existing automation kept working.
Read-only tokens are useful for dashboards, CI assertions, or analytics
collectors — anything that should never start a run.
When a read-only token hits a write endpoint, the server returns:
```json
{
"ok": false,
"error": {
"code": "FORBIDDEN",
"message": "Missing required scope: write. Issue a new token with the 'write' scope at /settings/api-keys."
}
}
```
HTTP status: `403`. See [Errors](/web/api/errors) for the full code table.
## Rate limits [#rate-limits]
### Per-PAT request limit [#per-pat-request-limit]
60 requests per 60 seconds per PAT, rolling window. When exceeded, the server
returns:
```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
{"ok":false,"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Retry after 60s."}}
```
### Per-user run-start limits [#per-user-run-start-limits]
`POST /api/v1/mogplex/runs` additionally enforces user-level run-start budgets:
* 10 run starts per minute
* 30 run starts per hour
* 150 run starts per day
These are independent of the per-PAT limit. A user with multiple PATs shares
the same run-start budget across them. Hitting any of these returns
`RATE_LIMITED` (429) with a `Retry-After` header.
If the limit-check backend is temporarily unavailable, the server returns
`SERVICE_UNAVAILABLE` (503) with `Retry-After: 60` so callers know not to
hammer.
## Idempotency-Key (required on mutations) [#idempotency-key-required-on-mutations]
`POST /api/v1/mogplex/runs` requires an `Idempotency-Key` header. The header
makes safe retries possible: the server records the key + a hash of the request
body, and replays the original result on a duplicate request.
```bash
KEY=$(uuidgen)
curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
-d '{"repoId":"","prompt":"Fix the tests"}' \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs"
```
Behavior:
* **Missing key** → 400 `BAD_REQUEST` `"Idempotency-Key is required"`.
* **Key longer than 200 chars** → 400 `BAD_REQUEST`.
* **Same key, same body** → replays the original result with `replayed: true` in the response data.
* **Same key, different body** → 409 `IDEMPOTENCY_CONFLICT`.
Use a fresh UUID per logical operation; reuse the same UUID across retries of
the same operation.
The CLI's `mogplex run` auto-generates an idempotency key via
`crypto.randomUUID()` when you don't pass `--idempotency-key`. Pass one
explicitly when you orchestrate your own retries.
## CLI browser handoff [#cli-browser-handoff]
The browser-based CLI login runs through `/cli-auth`:
1. The user runs `mogplex` in the terminal and chooses browser login.
2. The CLI opens `/cli-auth` with a localhost callback + nonce.
3. The page checks that the user is signed in (redirecting through `/login` if not), validates the callback, and shows a consent screen.
4. On consent, the server mints a PAT and POSTs it back to the CLI listener.
5. The CLI writes the token to `~/.mogplex/auth.json`.
The CLI never sees raw session cookies; the browser never sees the CLI's
private localhost port.
## Practical debugging [#practical-debugging]
If a request fails, identify which auth path you're on:
* **No `Authorization` header** → 401 `UNAUTHORIZED`. Set the header.
* **Header present, 401** → the token is invalid, expired, or revoked.
* **Header present, 403** → the token works but lacks the required scope. Re-issue with `write` if you're calling a mutation.
* **403 on a token-management route** → those routes require browser-session auth and reject PATs by design.
## Read next [#read-next]
* [Errors](/web/api/errors) — the full error code table and retry guidance
* [Runs](/web/api/runs) — the most common write endpoint, exercises every auth check above
* [Working Requests](/web/api/working-requests) — copy-paste curl examples for setup-state routes
# Errors (/web/api/errors)
Every `/api/v1/mogplex/*` endpoint returns a JSON envelope on both success and
failure. Branch on the `error.code` enum, not on the message string — messages
are user-friendly and may shift between releases.
## Envelope shape [#envelope-shape]
Success:
```json
{
"ok": true,
"data": { /* endpoint-specific */ }
}
```
Failure:
```json
{
"ok": false,
"error": {
"code": "FORBIDDEN",
"message": "Missing required scope: write. Issue a new token with the 'write' scope at /settings/api-keys."
}
}
```
The HTTP status code matches the error code per the table below.
## Error codes [#error-codes]
| `error.code` | HTTP | When you see it | What to do |
| ---------------------- | ---- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `BAD_REQUEST` | 400 | Malformed JSON, missing required field, invalid harness, missing `Idempotency-Key` on `POST /runs` | Fix the request shape and retry |
| `UNAUTHORIZED` | 401 | Missing, malformed, expired, or revoked PAT | Re-issue a token at [settings/api-keys](https://www.mogplex.com/settings/api-keys) |
| `FORBIDDEN` | 403 | Valid PAT but missing the required scope (e.g. read-only token hitting `POST /runs`) | Re-issue a token with the `write` scope |
| `NOT_FOUND` | 404 | Resource doesn't exist or isn't owned by the caller | Check the ID — most likely the resource was deleted or belongs to a different user |
| `CONFLICT` | 409 | Run already in a terminal state, sandbox not ready, lifecycle precondition failed | Inspect current state via `GET /runs/{id}` before retrying |
| `IDEMPOTENCY_CONFLICT` | 409 | Same `Idempotency-Key` reused with a **different** request body | Either use the same body or a fresh key |
| `RATE_LIMITED` | 429 | Per-PAT (60/min) or per-user run-start limit exceeded | Respect the `Retry-After` response header before retrying |
| `SERVICE_UNAVAILABLE` | 503 | Upstream limit-check backend unavailable | Retry with backoff (respect `Retry-After` if present) |
| `INTERNAL_ERROR` | 500 | Unexpected server error | Retry once with backoff; if persistent, report with the request ID from response headers |
## Retry guidance [#retry-guidance]
The codes split cleanly by whether retry will help:
* **Transient — retry with backoff:** `RATE_LIMITED` (429), `SERVICE_UNAVAILABLE` (503), `INTERNAL_ERROR` (500). Honor `Retry-After` when present.
* **Conditional — fix one thing first:** `CONFLICT` (409), `IDEMPOTENCY_CONFLICT` (409). Re-read state before retrying.
* **Permanent for this request — don't retry:** `BAD_REQUEST` (400), `UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404). Fix the request shape, credentials, or scope before issuing a new call.
The CLI's `MogplexApiClientError` exposes `isUnauthorized`, `isForbidden`, and
`isRateLimited` getters so command code can branch on common cases without
matching string codes. See [@mogplex/cloud-api](https://github.com/webrenew/mogplex-cli/blob/main/packages/cloud-api/src/errors.ts).
## Idempotency [#idempotency]
`POST /api/v1/mogplex/runs` requires an `Idempotency-Key` header (max 200 chars,
case-sensitive, your choice of format). The server records the key alongside a
hash of the request body:
* **Same key, same body** → replays the original result (`replayed: true` in the response).
* **Same key, different body** → returns `IDEMPOTENCY_CONFLICT` (409). Either use the same body or pick a new key.
* **No key** → returns `BAD_REQUEST` (400) with `"Idempotency-Key is required"`.
Use a UUID per logical request. The CLI's `mogplex run` auto-generates one when
you don't pass `--idempotency-key`.
## Rate limit headers [#rate-limit-headers]
When `RATE_LIMITED` (429) returns, the response includes:
```
Retry-After: 60
```
The window is a rolling 60 seconds per PAT for the per-key limit, or per-user
for the run-start limit. Per-user limits are configured at:
* 10 run starts per minute
* 30 run starts per hour
* 150 run starts per day
`SERVICE_UNAVAILABLE` (503) also sets `Retry-After: 60` when the limit backend
is temporarily unreachable.
## Read next [#read-next]
* [Authentication](/web/api/authentication) — how to issue, scope, and revoke PATs
* [Runs](/web/api/runs) — the most common endpoint that exercises every error code above
# Overview (/web/api)
The hosted API is Mogplex's control plane.
It is the surface the web app talks to for projects, repos, agents,
assignments, automations, sandboxes, settings, and runtime inspection.
This matters because it is **not** positioned like a stable versioned public
platform API yet. Route shape and response details follow the product, so treat
it as the live application surface behind Mogplex rather than a long-term
compatibility contract.
## Read this section in order [#read-this-section-in-order]
* [API Quickstart](/web/api/quickstart) for the shortest complete path from
token to repo lookup, run start, event inspection, cancellation, and sandbox
listing
* [Authentication](/web/api/authentication) for PAT lifecycle, scopes
(`read` / `write`), idempotency, and rate limits
* [Errors](/web/api/errors) for the typed error envelope, code table, and
retry guidance
* [Runs](/web/api/runs), [Repos](/web/api/repos), [Sandboxes](/web/api/sandboxes),
[MCP servers](/web/api/mcp-servers), [MCP](/web/api/mcp) for the v1 public
surface (`/api/v1/mogplex/*`)
* [Models](/web/api/models) for the standalone model catalog, CLI model export,
and per-user enablement rules
* [Working Requests](/web/api/working-requests) for concrete `curl` examples
on internal control-plane routes
* [Route Families](/web/api/route-families) for the broader control-plane map
## Start with safe first requests [#start-with-safe-first-requests]
If you only want the most useful first calls, start here:
* `GET /api/auth/user` to verify setup state, GitHub readiness, and platform
access
* `GET /api/settings` to inspect shared defaults like theme and default model
* `GET /api/models` to inspect the visible catalog and enabled model set
* `GET /api/github/installations` to confirm real GitHub App coverage
* `GET /api/v1/mogplex/mcp/servers` to export the CLI-ready MCP view (PAT-only)
* `GET /api/observability/stats` to inspect runtime health and cost summary
See [API Quickstart](/web/api/quickstart) for a complete run path and
[Working Requests](/web/api/working-requests) for broader route examples.
## How to read this API correctly [#how-to-read-this-api-correctly]
Read the hosted API in this order:
1. what product surface are you trying to drive?
2. which current route family backs that surface?
3. what auth mode is that route willing to accept?
If you start by assuming a clean public REST contract, you will overestimate how
stable the route shape is meant to be.
## The API is product-first [#the-api-is-product-first]
The easiest way to read the hosted API is:
* product state first
* route naming second
Most routes exist because the web app needs a control-plane surface for a real
product behavior, not because Mogplex has already frozen a generic external
REST contract.
That is why the route tree maps so closely to product areas like:
* settings and auth
* repos and workspaces
* agents and reusable libraries
* triggers, assignments, and flows
* sandbox runtime and observability
## Shared auth model [#shared-auth-model]
The same API is used by multiple Mogplex surfaces:
* the signed-in browser app
* the CLI when it talks to hosted Mogplex state
* internal automated tests
The current auth resolution order is:
1. `Authorization: Bearer mog_...` personal access token
2. internal Playwright auth headers used in end-to-end testing
3. browser session auth from the signed-in web app
That means many routes can support both browser and CLI callers without
inventing a second API namespace.
## Important auth nuance [#important-auth-nuance]
Not every route treats PAT auth the same way.
* Many shared read or control-plane routes accept PAT auth through the common
auth helper.
* Some sensitive routes intentionally require a real browser session and reject
PAT auth. Token-management endpoints are the clearest example.
If an API call works in the browser but fails from a PAT-backed script, check
whether the route uses the session-only auth helper instead of the generic one.
## Web and CLI crossover [#web-and-cli-crossover]
A few routes are intentionally designed for both surfaces:
* `/api/auth/user` returns app-aware setup state, including GitHub coverage and
linked-platform capability data
* `/api/settings` stores shared defaults like theme and the user's selected
`default_model`
* `/api/mcp-servers` returns a web-oriented shape by default, and
`/api/mcp-servers?format=cli` returns a CLI-oriented representation
The browser-based CLI login handoff runs through `/cli-auth`, not the `/api/*`
tree directly. That page validates the localhost callback requested by the CLI,
asks the user for consent inside the signed-in web app, and posts the resulting
token back to the CLI listener.
For the model split, see [Models](/web/api/models): `/api/models` is the
standalone model route, while `/api/settings` only returns or updates the
selected `default_model`.
## Route families [#route-families]
At a high level, the current `/api/*` tree breaks down into:
* **Identity and settings**: `/api/auth/*`, `/api/settings`, `/api/models`
* **Projects and GitHub state**: `/api/repos`, `/api/workspaces`,
`/api/github/*`
* **Reusable behavior**: `/api/agents`, `/api/agent-categories`, `/api/skills`,
`/api/rules`, `/api/mcp-servers`
* **Routing**: `/api/triggers`, `/api/assignments`, `/api/flows`
* **Runtime**: `/api/chat`, `/api/commands`, `/api/memories`, `/api/sandbox`,
`/api/observability/*`
* **System plumbing**: `/api/webhooks/*`, `/api/cron/*`, `/api/test/*`
See [Route Families](/web/api/route-families) for the concrete breakdown.
## Practical guidance [#practical-guidance]
Prefer the web app when you want the full Mogplex workflow and setup guidance.
Reach for the hosted API when you are:
* extending Mogplex from internal tooling
* wiring the CLI to hosted state
* building adjacent product code that should behave like the web app
* inspecting the current control-plane surface while implementing or debugging a
feature
If you depend on the hosted API directly today, document the specific routes
and payloads you rely on in your own integration. The product model is still
the source of truth.
# MCP servers (/web/api/mcp-servers)
`GET /api/v1/mogplex/mcp/servers`
Returns the merged list of MCP servers the authenticated user has configured
in Mogplex Cloud: custom servers stored in `user_mcp_servers` plus enabled
`mcp_server` connections. Secret values (env vars, headers, OAuth tokens) are
resolved server-side from Supabase Vault before the response is sent, so the
returned `config` block is ready to hand straight to a local MCP client.
Don't confuse this with [`POST /api/v1/mogplex/mcp`](/web/api/mcp). That
endpoint is the JSON-RPC tool-call surface for the **v1 REST API itself**.
This one lists the **user's external MCP servers** so a CLI or agent host
can connect to them locally.
## Scope [#scope]
`read` — see [Authentication → Scopes](/web/api/authentication#scopes). The
listing is gated on `read` explicitly because the response surfaces
authorization headers and vault-decrypted env vars.
## Merge rules [#merge-rules]
When a `user_mcp_servers` entry and an enabled `mcp_server` connection share
a name, the custom row wins — same precedence the CLI uses today via the
internal `/api/mcp-servers?format=cli` endpoint.
## Example [#example]
```bash
export MOGPLEX_BASE_URL="https://www.mogplex.com"
export MOGPLEX_TOKEN="mog_..."
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/mcp/servers"
```
Representative response:
```json
{
"ok": true,
"data": {
"servers": [
{
"name": "supabase",
"enabled": true,
"config": {
"command": "npx",
"args": ["@supabase/mcp-server"],
"env": {
"SUPABASE_ACCESS_TOKEN": "sbp_••••••••"
}
}
},
{
"name": "linear",
"enabled": true,
"config": {
"url": "https://mcp.linear.app/sse",
"http_headers": {
"Authorization": "Bearer lin_••••••••"
}
}
}
]
}
}
```
## Response shape [#response-shape]
```typescript
type MogplexApiMcpServer = {
name: string; // unique per user
enabled: boolean; // disabled servers are still returned
config: Record; // stdio: command/args/env
// http: url/http_headers
};
```
`config` is intentionally a loose record so the server can add transport
options without bumping the CLI. The two shapes in use today:
```typescript
// stdio
{ command: string; args?: string[]; env?: Record }
// http
{ url: string; http_headers?: Record }
```
## Errors [#errors]
| Code | HTTP | Cause |
| ---------------- | ---- | --------------------------- |
| `UNAUTHORIZED` | 401 | Missing/invalid/expired PAT |
| `FORBIDDEN` | 403 | PAT lacks the `read` scope |
| `RATE_LIMITED` | 429 | 60 req/min per PAT exceeded |
| `INTERNAL_ERROR` | 500 | Unexpected server error |
See [Errors](/web/api/errors) for retry guidance.
## CLI equivalent [#cli-equivalent]
The Mogplex CLI calls this endpoint automatically on startup to refresh
`~/.mogplex/mcp-servers.remote.json`. There's no dedicated subcommand — see
[Headless runs](/cli/automation/headless-runs) for how the CLI uses these
servers during agent runs.
## Security notes [#security-notes]
* Responses include decrypted secrets. Treat them like a `.env` file: don't
log them, don't commit them, don't echo them in CI output.
* The endpoint requires the `read` scope and never falls back to session
cookies — a PAT is the only way in.
## Read next [#read-next]
* [Connections and MCP](/configure-and-extend/connections-and-mcp) — the
product configuration model behind MCP server sync
* [MCP server (JSON-RPC)](/web/api/mcp) — the v1-as-MCP-tools surface
* [Authentication](/web/api/authentication) — PAT lifecycle and scopes
# MCP server (/web/api/mcp)
`POST /api/v1/mogplex/mcp`
The Mogplex Cloud API is also reachable as an [MCP](https://modelcontextprotocol.io/)
server over JSON-RPC 2.0. Each tool mirrors a v1 REST endpoint, so a host that
understands MCP gets the full surface without writing a REST client.
Looking for the list of MCP servers you've configured in Mogplex (Linear,
Supabase, etc.)? That's a different endpoint — see
[GET /api/v1/mogplex/mcp/servers](/web/api/mcp-servers).
## Connecting [#connecting]
| Header | Value |
| --------------- | --------------------------- |
| `Authorization` | `Bearer mog_...` (your PAT) |
| `Content-Type` | `application/json` |
| `Accept` | `application/json` |
The server responds with `mcp-protocol-version: 2025-11-25` and a JSON-RPC 2.0
body. Scopes still apply: tools that wrap mutating endpoints require the
`write` scope; read tools require `read`.
## Methods [#methods]
| Method | Description |
| ------------ | --------------------------------------------------- |
| `initialize` | Returns server info, capabilities, and instructions |
| `ping` | Returns `{}` |
| `tools/list` | Returns the list of available tools |
| `tools/call` | Invokes a tool |
## Initialize [#initialize]
```bash
curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize"}' \
"$MOGPLEX_BASE_URL/api/v1/mogplex/mcp"
```
Response:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-11-25",
"capabilities": { "tools": { "listChanged": false } },
"serverInfo": { "name": "mogplex", "version": "0.1.0" },
"instructions": "Use Mogplex tools to list repos, start repo-bound agent runs, fetch run state and events, and request cancellation."
}
}
```
## Tools [#tools]
### mogplex\_list\_repos [#mogplex_list_repos]
Wraps [`GET /repos`](/web/api/repos). Scope: `read`.
```json
{
"name": "mogplex_list_repos",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "Case-insensitive substring filter" },
"limit": { "type": "integer", "minimum": 1, "maximum": 200 }
}
}
}
```
### mogplex\_list\_sandboxes [#mogplex_list_sandboxes]
Wraps [`GET /sandboxes`](/web/api/sandboxes). Scope: `read`.
```json
{
"name": "mogplex_list_sandboxes",
"inputSchema": {
"type": "object",
"properties": {
"repoId": { "type": "string" },
"status": { "type": "string" },
"limit": { "type": "integer", "minimum": 1, "maximum": 200 }
}
}
}
```
### mogplex\_start\_agent\_run [#mogplex_start_agent_run]
Wraps [`POST /runs`](/web/api/runs). Scope: `write`.
```json
{
"name": "mogplex_start_agent_run",
"inputSchema": {
"type": "object",
"required": ["repoId", "prompt"],
"properties": {
"repoId": { "type": "string" },
"prompt": { "type": "string" },
"harness": { "type": "string", "enum": ["codex", "claude-code"] },
"baseBranch": { "type": "string" },
"workingBranch": { "type": "string" },
"createBranch": { "type": "boolean" },
"rootDirectory": { "type": ["string", "null"] },
"idempotencyKey": { "type": "string", "maxLength": 200 }
}
}
}
```
If `idempotencyKey` is omitted, the server generates one. Pass an explicit key
when orchestrating your own retries.
### mogplex\_get\_run [#mogplex_get_run]
Wraps [`GET /runs/{runId}`](/web/api/runs#get-a-run). Scope: `read`.
```json
{
"name": "mogplex_get_run",
"inputSchema": {
"type": "object",
"required": ["runId"],
"properties": { "runId": { "type": "string" } }
}
}
```
### mogplex\_get\_run\_events [#mogplex_get_run_events]
Wraps [`GET /runs/{runId}/events`](/web/api/runs#list-run-events). Scope: `read`.
```json
{
"name": "mogplex_get_run_events",
"inputSchema": {
"type": "object",
"required": ["runId"],
"properties": {
"runId": { "type": "string" },
"limit": { "type": "integer", "minimum": 1, "maximum": 200 }
}
}
}
```
### mogplex\_cancel\_run [#mogplex_cancel_run]
Wraps [`POST /runs/{runId}/cancel`](/web/api/runs#cancel-a-run). Scope: `write`.
```json
{
"name": "mogplex_cancel_run",
"inputSchema": {
"type": "object",
"required": ["runId"],
"properties": { "runId": { "type": "string" } }
}
}
```
## Calling a tool [#calling-a-tool]
```bash
curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 42,
"method": "tools/call",
"params": {
"name": "mogplex_list_repos",
"arguments": { "limit": 5 }
}
}' \
"$MOGPLEX_BASE_URL/api/v1/mogplex/mcp"
```
Response:
```json
{
"jsonrpc": "2.0",
"id": 42,
"result": {
"content": [
{ "type": "text", "text": "{\n \"repos\": [...]\n}" }
]
}
}
```
The tool's REST envelope is serialized into the `content[0].text` JSON. Parse
it on the client to read individual fields.
## Errors [#errors]
JSON-RPC errors map to MCP error codes plus HTTP status:
| JSON-RPC code | HTTP | Meaning |
| ------------- | ---- | --------------------------- |
| `-32700` | 400 | Parse error — invalid JSON |
| `-32600` | 400 | Invalid request |
| `-32601` | 200 | Method not found |
| `-32602` | 200 | Invalid tool arguments |
| `-32001` | 401 | Unauthorized |
| `-32002` | 429 | Rate limit exceeded |
| `-32003` | 403 | Forbidden (origin or scope) |
| `-32603` | 200 | Internal error |
Tool calls that hit the underlying REST endpoint's errors (e.g. `FORBIDDEN`,
`NOT_FOUND`) return them inside the tool result, not as JSON-RPC errors.
## CORS [#cors]
Same-origin requests always pass. Cross-origin requests are accepted from the
origins listed in `MOGPLEX_MCP_ALLOWED_ORIGINS` on the server. The `OPTIONS`
preflight returns:
```
access-control-allow-headers: authorization, content-type, mcp-protocol-version, mcp-session-id
```
## When to use MCP vs REST [#when-to-use-mcp-vs-rest]
Use MCP when your agent host speaks it natively (Claude Code, Claude Desktop,
the Claude Agent SDK). Use REST or the headless CLI for everything else — the
surface is the same, MCP just packages it for MCP-aware hosts.
## Read next [#read-next]
* [Runs](/web/api/runs) — the REST equivalents the tools wrap
* [Authentication](/web/api/authentication) — PAT scopes apply to MCP tools too
* [Headless runs](/cli/automation/headless-runs) — a CLI alternative when MCP isn't an option
# Models (/web/api/models)
`/api/models` is the standalone model route in Mogplex.
Use it when you need model availability, enabled state, or CLI picker data.
If you want the user-facing guide instead of the route contract, start with
[Available Models](/web/models).
Do **not** use `/api/settings` for that broader job. `/api/settings` only
returns or updates the selected `default_model` preference after Mogplex has
resolved it against the current catalog and the user's enabled-state rules.
## What this route owns [#what-this-route-owns]
`/api/models` is the route for:
* the visible model catalog
* the subset of models enabled for the current user
* CLI-formatted model lists
* per-user enable or disable preferences
It is **not** the route for:
* changing the shared global model catalog
* choosing which enabled model is the current default
The underlying split is:
* Supabase `ai_models` holds the canonical catalog
* `user_model_preferences` holds per-user enable or disable state
* the profile row stores the selected `default_model`
## `GET /api/models` [#get-apimodels]
This route always returns the same top-level keys:
* `catalog`
* `models`
What changes is how those keys are populated:
* with user auth, `catalog` includes visible models plus per-model
`is_enabled`, and `models` is the enabled subset the user can actively use
* without user auth, both `catalog` and `models` are the same visible
available catalog
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/models"
```
Representative response excerpt:
```json
{
"models": [
{
"id": "provider/model-a",
"provider": "provider",
"name": "Model A",
"is_available": true,
"is_enabled": true,
"capabilities": ["chat", "tools"]
}
],
"catalog": [
{
"id": "provider/model-a",
"provider": "provider",
"name": "Model A",
"is_available": true,
"is_enabled": true,
"capabilities": ["chat", "tools"]
},
{
"id": "provider/model-b",
"provider": "provider",
"name": "Model B",
"is_available": true,
"is_enabled": false
}
]
}
```
Unauthenticated response excerpt:
```json
{
"models": [
{
"id": "provider/model-a",
"provider": "provider",
"name": "Model A",
"is_available": true
}
],
"catalog": [
{
"id": "provider/model-a",
"provider": "provider",
"name": "Model A",
"is_available": true
}
]
}
```
Practical behavior to know:
* unauthenticated callers still get both keys, but they point at the same
visible available catalog
* authenticated callers get `catalog` plus the enabled `models` subset
* visibility filtering applies before the response is returned
* recommendation metadata, pricing, context length, and capabilities can also
appear when present in the catalog
## `GET /api/models?format=cli` [#get-apimodelsformatcli]
Use the CLI format when a terminal client or internal tool needs the model list
in the same shape the CLI picker expects.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/models?format=cli"
```
This route intentionally keeps CLI parity with the hosted product state:
* models explicitly disabled by the user are removed from the CLI list
* available models that are not explicitly disabled remain visible, even in the
CLI-oriented shape
## `PATCH /api/models` [#patch-apimodels]
Use `PATCH` to enable or disable a model for the current user.
```bash
curl -sS \
-X PATCH \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model_id":"provider/model-b","is_enabled":true}' \
"$MOGPLEX_BASE_URL/api/models"
```
Representative success response:
```json
{
"ok": true
}
```
Two rules matter:
* `model_id` and `is_enabled` are required
* catalog fields like `provider`, `name`, or `is_available` are rejected here
If you try to mutate the shared catalog through `/api/models`, Mogplex returns
`400` because catalog updates belong to the sync path, not to per-user API
preference writes.
## When to use `/api/models` vs `/api/settings` [#when-to-use-apimodels-vs-apisettings]
Use `/api/models` when you need:
* the full visible model catalog
* enabled or disabled model state
* CLI-ready model export
* per-user model preference writes
Use `/api/settings` when you need:
* the currently selected `default_model`
* theme and other shared user defaults
That split is the fastest way to avoid reaching for the wrong route.
## Read next [#read-next]
* [Available Models](/web/models) for the product-facing model access guide
* [Working Requests](/web/api/working-requests) for copy-paste requests across
the most useful route families
* [Route Families](/web/api/route-families) for the broader control-plane map
# API Quickstart (/web/api/quickstart)
Use this quickstart when you want to drive Mogplex from a script, internal
tool, CI job, or dashboard.
The hosted API is still product-first. It is the control plane behind the web
app and CLI, not a frozen compatibility contract for every internal route. For
the most stable external surface, start with `/api/v1/mogplex/*`.
## Prerequisites [#prerequisites]
Before calling the API:
1. sign in to the web app
2. create a personal access token in [Settings](/web/settings)
3. make sure the repo is imported and visible in [Projects](/web/spaces)
4. make sure the token has `read` for list/detail calls and `write` for run
starts or cancellation
Set these once in your shell:
```bash
export MOGPLEX_BASE_URL="https://www.mogplex.com"
export MOGPLEX_TOKEN="mog_..."
```
Every request below uses the same bearer header:
```bash
-H "Authorization: Bearer $MOGPLEX_TOKEN"
```
## 1. Verify the account [#1-verify-the-account]
Start with account state. This tells you whether the token works and whether
GitHub, managed model access, and managed sandbox access look ready.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/auth/user"
```
If this returns `401`, fix the token before debugging repos, runs, models, or
sandboxes.
## 2. List repos [#2-list-repos]
Use the v1 repos route to find the `repoId` required by run starts.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/repos?q=acme&limit=20"
```
The response includes the repo id, full name, default branch, and root
directory when Mogplex has one stored.
```json
{
"ok": true,
"data": {
"repos": [
{
"id": "8f3a2b1c-1234-4abc-9def-1234567890ab",
"full_name": "acme/web",
"default_branch": "main",
"root_directory": "apps/web"
}
]
}
}
```
If the repo is missing, check [GitHub App Coverage](/web/guides/github-app-coverage)
and [Projects](/web/spaces) before starting a run.
## 3. Check model availability [#3-check-model-availability]
Use the model route when your script needs to show choices or confirm the
account has at least one enabled model.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/models?format=cli"
```
Use [Available Models](/web/models) for the product-facing model guide and
[API Models](/web/api/models) for the route contract.
## 4. Start a run [#4-start-a-run]
Starting a run is a write operation and requires an `Idempotency-Key`.
```bash
RUN_RESPONSE=$(curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"repoId": "8f3a2b1c-1234-4abc-9def-1234567890ab",
"prompt": "Inspect the failing test suite and propose the smallest fix.",
"harness": "codex",
"baseBranch": "main",
"createBranch": true,
"rootDirectory": "apps/web"
}' \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs")
echo "$RUN_RESPONSE"
```
Representative response:
```json
{
"ok": true,
"data": {
"runId": "run-uuid",
"status": "pending",
"eventsUrl": "/api/v1/mogplex/runs/run-uuid/events",
"cancelUrl": "/api/v1/mogplex/runs/run-uuid/cancel",
"branch": {
"base": "main",
"working": "mogplex/run/YYYY-MM-DD/inspect-tests",
"createBranch": true
},
"replayed": false
}
}
```
Use a fresh idempotency key per logical run start. Reuse the same key only when
retrying the same request body.
## 5. Inspect the run [#5-inspect-the-run]
Fetch current run state:
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid"
```
Fetch recent events:
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/events?limit=100"
```
Terminal statuses are:
| Status | Meaning |
| ----------- | ------------------------------------------- |
| `success` | The run completed without error |
| `failed` | The agent or sandbox failed |
| `cancelled` | Cancellation was requested and acknowledged |
Non-terminal statuses such as `pending` and `streaming` mean the run is still
being allocated or is actively producing events.
## 6. Cancel a run [#6-cancel-a-run]
Cancellation is a write operation.
```bash
curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/cancel"
```
Cancellation is idempotent. If the run is already terminal, the endpoint
returns the terminal state without starting another cancellation path.
## 7. Inspect sandboxes [#7-inspect-sandboxes]
Use sandboxes when the runtime or preview is the thing you need to inspect.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/sandboxes?repo_id=8f3a2b1c-1234-4abc-9def-1234567890ab&status=running"
```
The v1 API currently lists sandboxes. Lifecycle operations such as stop, pause,
resume, or delete belong in the web UI until the lifecycle routes are exposed.
## First error map [#first-error-map]
| Symptom | Start here |
| ------------------------------- | ------------------------------------------------------------------ |
| `401 UNAUTHORIZED` | Token is missing, invalid, expired, or revoked |
| `403 FORBIDDEN` | Token works but lacks the required scope |
| `400 BAD_REQUEST` on run start | Check `Idempotency-Key`, `repoId`, `prompt`, branch, and harness |
| `404 NOT_FOUND` for repo or run | The id does not belong to the authenticated user |
| `409 IDEMPOTENCY_CONFLICT` | Same idempotency key was reused with a different body |
| `429 RATE_LIMITED` | Respect `Retry-After` and reduce request or run-start rate |
| No repo appears | Fix GitHub App coverage or repo import before API work |
| No model is usable | Check [Available Models](/web/models) and plan-backed model access |
## Read next [#read-next]
# Repos (/web/api/repos)
`GET /api/v1/mogplex/repos`
Returns the list of repos imported into the caller's Mogplex account. Use the
returned `id` as `repoId` when starting a run via [POST /runs](/web/api/runs)
or as `repo_id` when filtering [sandboxes](/web/api/sandboxes).
## Scope [#scope]
`read` — see [Authentication → Scopes](/web/api/authentication#scopes).
## Query parameters [#query-parameters]
| Param | Type | Default | Notes |
| ------- | ------- | ------- | ------------------------------------------------ |
| `q` | string | — | Case-insensitive substring filter on `full_name` |
| `limit` | integer | 100 | 1–200 |
## Example [#example]
```bash
export MOGPLEX_BASE_URL="https://www.mogplex.com"
export MOGPLEX_TOKEN="mog_..."
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/repos?limit=10"
```
Representative response:
```json
{
"ok": true,
"data": {
"repos": [
{
"id": "8f3a2b1c-1234-4abc-9def-1234567890ab",
"full_name": "acme/web",
"default_branch": "main",
"root_directory": null
},
{
"id": "1a2b3c4d-5678-4abc-9def-1234567890cd",
"full_name": "acme/api",
"default_branch": "main",
"root_directory": "services/api"
}
]
}
}
```
Filter by substring:
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/repos?q=web"
```
## Response shape [#response-shape]
```typescript
type MogplexApiRepo = {
id: string; // UUID — use as repoId in POST /runs
full_name: string; // owner/repo (GitHub convention)
default_branch: string | null; // null when GitHub doesn't expose it
root_directory: string | null; // monorepo subpath, null for repo root
};
```
## Errors [#errors]
| Code | HTTP | Cause |
| ---------------- | ---- | --------------------------- |
| `UNAUTHORIZED` | 401 | Missing/invalid/expired PAT |
| `RATE_LIMITED` | 429 | 60 req/min per PAT exceeded |
| `INTERNAL_ERROR` | 500 | Unexpected server error |
See [Errors](/web/api/errors) for retry guidance.
## CLI equivalent [#cli-equivalent]
```bash
mogplex repos list # pretty table
mogplex repos list --json # one JSON object per line
mogplex repos list --query web --limit 10
```
See [Headless runs](/cli/automation/headless-runs).
## Read next [#read-next]
* [Runs](/web/api/runs) — start a run against one of these repos
* [Sandboxes](/web/api/sandboxes) — filter sandboxes by `repo_id`
# Route Families (/web/api/route-families)
The hosted API is easiest to understand when you read it as a control plane,
not as a generic public REST surface.
Most route groups map directly to a product area.
If you want copy-paste examples first, go to
[Working Requests](/web/api/working-requests) and then come back here.
## v1 public surface [#v1-public-surface]
Representative routes:
* `/api/v1/mogplex/repos` (GET)
* `/api/v1/mogplex/sandboxes` (GET)
* `/api/v1/mogplex/runs` (POST)
* `/api/v1/mogplex/runs/{runId}` (GET)
* `/api/v1/mogplex/runs/{runId}/events` (GET)
* `/api/v1/mogplex/runs/{runId}/cancel` (POST)
* `/api/v1/mogplex/mcp/servers` (GET)
* `/api/v1/mogplex/mcp` (POST, JSON-RPC)
This is the stable, **PAT-only** surface for headless callers — the CLI's
`mogplex repos|run|runs|sandboxes` commands, the in-app MCP server, and any
third-party integration. Every endpoint returns the same typed envelope
documented at [Errors](/web/api/errors), and mutations enforce the `write`
scope per [Authentication](/web/api/authentication).
Good first calls in this family:
* `GET /api/v1/mogplex/repos` to discover repo IDs
* `POST /api/v1/mogplex/runs` (with `Idempotency-Key`) to start an agent run
* `GET /api/v1/mogplex/runs/{id}/events` to tail it
Read [Runs](/web/api/runs) for a full walkthrough.
This family is intentionally narrower than the internal control-plane families
below — it covers headless agent-run automation and nothing else. Other
behaviors stay on the internal `/api/*` surface until they have a stable
public contract.
## Identity and setup [#identity-and-setup]
Representative routes:
* `/api/auth/*`
* `/api/auth/user`
* `/api/settings`
* `/api/settings/keys`
* `/api/settings/api-keys`
* `/api/models`
These routes answer questions like:
* who is the current user in Mogplex terms?
* what GitHub/App/Vercel setup state should the UI show?
* what access tokens, defaults, managed access, and models are available?
One important implementation detail:
* the canonical model catalog lives in Supabase `ai_models`
* per-user enabled or disabled state lives in `user_model_preferences`
* the selected default model id lives on the profile row
* `/api/models` is the standalone route that exposes the catalog and
user-visible enabled model set
* `/api/settings` resolves the stored profile `default_model` against that
catalog and enabled-state rules before returning it
See [Models](/web/api/models) for the route-specific GET, CLI-format, and
PATCH behavior.
That means the split is:
* use `/api/models` when you need models
* use `/api/settings` when you need the selected default model preference
Good first calls in this family:
* `GET /api/auth/user` for overall readiness
* `GET /api/settings` for shared user defaults
* `GET /api/models` for the standalone model catalog and enabled model set
This family matters because setup state is first-class in the product. The UI
does not just assume the account is ready.
## Projects, repos, and GitHub coverage [#projects-repos-and-github-coverage]
Representative routes:
* `/api/repos`
* `/api/repos/[id]`
* `/api/workspaces`
* `/api/workspaces/[id]`
* `/api/github/installations`
* `/api/github/repos`
* `/api/github/owners`
* `/api/github/pulls`
These routes manage the imported repo graph the rest of Mogplex builds on.
Good first calls in this family:
* `GET /api/github/installations` when webhook-backed routing looks empty
* `GET /api/repos` when Projects state itself looks wrong
If routing, repo visibility, monorepo structure, or sandbox ownership feels
wrong, this is often the state layer to inspect first.
## Connections and reusable libraries [#connections-and-reusable-libraries]
Representative routes:
* `/api/connections`
* `/api/connections/[id]`
* `/api/connections/oauth`
* `/api/mcp-servers`
* `/api/mcp-servers/[id]`
* `/api/agents`
* `/api/agents/roster`
* `/api/agents/generate`
* `/api/agent-categories`
* `/api/skills`
* `/api/skills/registry`
* `/api/skills/vercel-docs`
* `/api/rules`
This is the reusable behavior layer behind:
* agent definitions
* categories
* MCP server sync
* connection health
* rules, skills, and shared context libraries
Good first calls in this family:
* `GET /api/mcp-servers?format=cli` when the CLI should mirror hosted MCP state
* `GET /api/connections` when tool access feels configured wrong
If the product feels "configured wrong" rather than "running wrong", this is
often the route family involved.
## Routing surfaces [#routing-surfaces]
Representative routes:
* `/api/triggers`
* `/api/assignments`
* `/api/flows`
* `/api/flows/[id]`
These routes back the three durable routing models in Mogplex:
* installation-scoped event routing
* repo-scoped standing work
* multi-step workflow graphs
They matter because Mogplex treats event routing, repo responsibility, and
workflow orchestration as different product models instead of one overloaded
object.
Good first calls in this family:
* `GET /api/flows` to list existing automations
* `POST /api/flows` to create a new automation shell for one installation
## Conversations, memory, and live agent work [#conversations-memory-and-live-agent-work]
Representative routes:
* `/api/chat`
* `/api/conversations`
* `/api/commands`
* `/api/memories`
* `/api/memories/actions`
These routes support active work once the user is already inside a workspace or
live session.
This family is about ongoing agent interaction, not just setup or routing.
## Sandbox runtime and observability [#sandbox-runtime-and-observability]
Representative routes:
* `/api/sandbox`
* `/api/sandbox/[id]`
* `/api/observability/stats`
* `/api/observability/calls`
* `/api/observability/call-events`
* `/api/observability/jobs`
* `/api/observability/automation-events`
* `/api/observability/automation-failures`
* `/api/observability/tool-calls`
If the routing surface answers "what should run?", these routes answer:
* what is running now?
* what call or job failed?
* which sandbox was involved?
* how much did it cost?
* what tool calls happened?
Good first calls in this family:
* `GET /api/observability/stats` for compressed health and cost signals
* `GET /api/sandbox/[id]` when you already know the sandbox you need to inspect
## System plumbing and internal operations [#system-plumbing-and-internal-operations]
Representative routes:
* `/api/webhooks/github`
* `/api/cron/*`
* `/api/jobs`
* `/api/jobs/process`
* `/api/test/*`
* `/api/migrate`
These are not the main user-facing control surfaces, but they matter when you
are debugging the product as a whole.
This family includes:
* webhook ingestion
* scheduled repair and sync jobs
* internal processing routes
* test helpers
* migration and maintenance paths
You usually do not start in this family unless you are debugging Mogplex
itself.
## A useful mental model [#a-useful-mental-model]
When you are trying to find the right route family, ask one question first:
**Is this about setup, reusable definition, routing, active execution, or system
maintenance?**
That usually narrows the relevant API surface immediately.
## Product-first, not platform-first [#product-first-not-platform-first]
This is the key architectural point:
the Mogplex API is still organized around product behavior, not around a frozen
versioned public contract.
So if you build on it directly:
* depend on specific routes intentionally
* document the exact payloads you rely on
* expect the product model to remain the source of truth
# Runs (/web/api/runs)
Four endpoints cover the run lifecycle:
| Endpoint | Method | Scope | Purpose |
| ------------------------------------- | ------ | ------- | ----------------------------------------- |
| `/api/v1/mogplex/runs` | POST | `write` | Start a run |
| `/api/v1/mogplex/runs/{runId}` | GET | `read` | Get a run's current state |
| `/api/v1/mogplex/runs/{runId}/events` | GET | `read` | List run events (sanitized, oldest-first) |
| `/api/v1/mogplex/runs/{runId}/cancel` | POST | `write` | Request cancellation |
## Start a run [#start-a-run]
`POST /api/v1/mogplex/runs`
Required headers:
* `Authorization: Bearer mog_...`
* `Content-Type: application/json`
* `Idempotency-Key` — see [Authentication → Idempotency-Key](/web/api/authentication#idempotency-key-required-on-mutations)
Request body:
```typescript
type StartMogplexApiRunRequest = {
repoId: string; // Required — get from GET /repos
prompt: string; // Required — max 100,000 chars
harness?: "codex" | "claude-code"; // Default: "codex"
baseBranch?: string; // Default: repo default_branch (or "main")
workingBranch?: string; // Default: baseBranch (or a generated name when createBranch=true)
createBranch?: boolean; // If true, create/use the generated working branch
rootDirectory?: string | null; // Monorepo subpath
conversationId?: string | null; // Attach to an existing conversation
workspaceSessionId?: string | null; // Attach to an existing workspace session
mode?: string | null; // Mode hint for the runtime
};
```
### Example [#example]
```bash
export MOGPLEX_BASE_URL="https://www.mogplex.com"
export MOGPLEX_TOKEN="mog_..."
curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"repoId": "8f3a2b1c-1234-4abc-9def-1234567890ab",
"prompt": "Refactor the auth module to use bearer tokens instead of cookies.",
"harness": "codex",
"baseBranch": "main",
"createBranch": true
}' \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs"
```
Response (HTTP `202 Accepted`):
```json
{
"ok": true,
"data": {
"runId": "run-uuid",
"aiCallId": "call-uuid",
"sandboxRecordId": "sandbox-record-uuid",
"sandboxId": null,
"repoId": "8f3a2b1c-1234-4abc-9def-1234567890ab",
"harness": "codex",
"status": "pending",
"branch": {
"base": "main",
"working": "mogplex/run/2026-05-17/refactor-auth",
"createBranch": true
},
"rootDirectory": null,
"eventsUrl": "/api/v1/mogplex/runs/run-uuid/events",
"cancelUrl": "/api/v1/mogplex/runs/run-uuid/cancel",
"createdAt": "2026-05-17T10:14:00.000Z",
"updatedAt": "2026-05-17T10:14:00.000Z",
"error": null,
"runtime": {
"provider": "trigger",
"runId": "trigger-run-uuid"
},
"replayed": false
}
}
```
If you POST the same body with the same `Idempotency-Key`, `replayed` becomes
`true` and `runId` matches the first call.
### Status values [#status-values]
| Status | Meaning |
| ----------- | -------------------------------------------------- |
| `pending` | Accepted, waiting on sandbox + runtime allocation |
| `streaming` | Agent is actively producing events |
| `success` | Terminal — agent completed without error |
| `failed` | Terminal — agent or sandbox failed |
| `cancelled` | Terminal — cancellation requested and acknowledged |
### Errors [#errors]
| Code | HTTP | Cause |
| ---------------------- | ---- | ------------------------------------------------------------------------------------------ |
| `UNAUTHORIZED` | 401 | Missing/invalid PAT |
| `FORBIDDEN` | 403 | PAT lacks `write` scope |
| `BAD_REQUEST` | 400 | Missing `Idempotency-Key`, missing `repoId`/`prompt`, invalid harness, invalid branch name |
| `NOT_FOUND` | 404 | `repoId` doesn't belong to the caller |
| `IDEMPOTENCY_CONFLICT` | 409 | Same key used with a different body |
| `RATE_LIMITED` | 429 | Per-PAT (60/min) or per-user run-start budget exceeded |
| `SERVICE_UNAVAILABLE` | 503 | Limit-check backend unavailable |
| `INTERNAL_ERROR` | 500 | Unexpected server error |
See [Errors](/web/api/errors).
## Get a run [#get-a-run]
`GET /api/v1/mogplex/runs/{runId}`
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid"
```
Response:
```json
{
"ok": true,
"data": {
"run": {
"runId": "run-uuid",
"status": "streaming",
"harness": "codex",
"repoId": "8f3a2b1c-...",
"branch": { "base": "main", "working": "feat/x", "createBranch": true },
"sandboxId": "vsb_abc",
"createdAt": "2026-05-17T10:14:00.000Z",
"updatedAt": "2026-05-17T10:15:30.000Z",
"error": null,
"eventsUrl": "/api/v1/mogplex/runs/run-uuid/events",
"cancelUrl": "/api/v1/mogplex/runs/run-uuid/cancel",
"runtime": { "provider": "trigger", "runId": "..." }
}
}
}
```
Errors: `UNAUTHORIZED` (401), `NOT_FOUND` (404), `RATE_LIMITED` (429), `INTERNAL_ERROR` (500).
## List run events [#list-run-events]
`GET /api/v1/mogplex/runs/{runId}/events`
Returns the event stream for a run, oldest first. Useful for polling, replay,
or tailing from CI.
Query parameters:
| Param | Type | Default | Notes |
| ------- | ------- | ------- | ----- |
| `limit` | integer | 100 | 1–200 |
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/events?limit=50"
```
Response:
```json
{
"ok": true,
"data": {
"run": { /* same shape as GET /runs/{runId} */ },
"events": [
{
"id": "event-uuid",
"type": "stream_started",
"toolName": null,
"message": "Agent started",
"payload": {},
"createdAt": "2026-05-17T10:14:10.000Z"
},
{
"id": "event-uuid-2",
"type": "tool_call",
"toolName": "edit_file",
"message": "Editing src/auth.ts",
"payload": { "path": "src/auth.ts" },
"createdAt": "2026-05-17T10:14:15.000Z"
}
]
}
}
```
Event payloads are sanitized server-side: sensitive keys (env vars, GitHub
tokens, AI billing source) are redacted; strings over 2,000 chars are
truncated; arrays/objects are capped at 25 items / depth 3 / 20 KB JSON. The
goal is safe inclusion in dashboards and logs without leaking secrets.
### Polling for terminal status [#polling-for-terminal-status]
Polling pattern in pseudocode:
```
loop:
events = GET /runs/{id}/events
emit events.events (de-duped by id)
if events.run.status in {success, failed, cancelled}: break
sleep 1.5s
```
The CLI's `mogplex runs events --follow` implements this with a 1.5s poll
interval and a configurable `--timeout` (default 1800s).
Errors: `UNAUTHORIZED` (401), `NOT_FOUND` (404), `RATE_LIMITED` (429), `INTERNAL_ERROR` (500).
## Cancel a run [#cancel-a-run]
`POST /api/v1/mogplex/runs/{runId}/cancel`
Idempotent. Requesting cancellation on a run that's already terminal returns
the terminal state with no side effects.
```bash
curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/runs/run-uuid/cancel"
```
Response:
```json
{
"ok": true,
"data": {
"run": { /* MogplexApiRunDetail */ },
"status": "cancellation_requested"
}
}
```
Possible `status` values:
* `cancellation_requested` — agent signaled, will reach `cancelled` shortly
* `already_terminal` — run was already in `success` / `failed` / `cancelled`
Errors: `UNAUTHORIZED` (401), `FORBIDDEN` (403, missing `write` scope), `NOT_FOUND` (404), `CONFLICT` (409, sandbox unreachable), `INTERNAL_ERROR` (500).
## CLI equivalents [#cli-equivalents]
```bash
# Start
mogplex run --repo --harness codex "Refactor auth module"
# Inspect
mogplex runs get
mogplex runs events --follow --timeout 600
mogplex runs cancel
```
See [Headless runs](/cli/automation/headless-runs) for a fuller walkthrough.
## Read next [#read-next]
* [Errors](/web/api/errors) — full error code table
* [Authentication](/web/api/authentication) — PAT scopes and idempotency
* [MCP](/web/api/mcp) — the same surface exposed as a JSON-RPC MCP server
# Sandboxes (/web/api/sandboxes)
`GET /api/v1/mogplex/sandboxes`
Lists cloud sandboxes the caller owns. Useful for cleanup scripts, dashboards,
or scoping a run to an existing branch.
v1 sandbox lifecycle routes (stop / pause / resume / get-by-id) are not yet
exposed. They will land alongside the sandbox-lifecycle refactor. Until then,
use the web UI at `mogplex.com/sandboxes/{id}` for lifecycle actions.
## Scope [#scope]
`read` — see [Authentication → Scopes](/web/api/authentication#scopes).
## Query parameters [#query-parameters]
| Param | Type | Default | Notes |
| --------- | ------- | ------- | --------------------------------------------- |
| `repo_id` | string | — | UUID; restrict to sandboxes for a single repo |
| `status` | string | — | e.g. `running`, `paused`, `stopped`, `error` |
| `limit` | integer | 100 | 1–200 |
## Example [#example]
```bash
export MOGPLEX_BASE_URL="https://www.mogplex.com"
export MOGPLEX_TOKEN="mog_..."
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/sandboxes?status=running&limit=20"
```
Representative response:
```json
{
"ok": true,
"data": {
"sandboxes": [
{
"id": "sandbox-uuid",
"sandbox_id": "vsb_acme_web_main",
"repo_id": "8f3a2b1c-1234-4abc-9def-1234567890ab",
"status": "running",
"base_branch": "main",
"working_branch": "feat/refactor-auth",
"root_directory": null,
"preview_url": "https://abc123.sandbox.mogplex.com",
"created_at": "2026-05-17T10:14:00.000Z",
"last_active_at": "2026-05-17T10:42:00.000Z"
}
]
}
}
```
Filter by repo:
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/v1/mogplex/sandboxes?repo_id=8f3a2b1c-..."
```
## Response shape [#response-shape]
```typescript
type MogplexApiSandbox = {
id: string; // Mogplex sandbox record UUID
sandbox_id: string | null; // Underlying provider sandbox ID (may be null pre-allocation)
repo_id: string;
status: string; // e.g. "running", "paused", "stopped", "error"
base_branch: string;
working_branch: string;
root_directory: string | null; // Monorepo subpath
preview_url: string | null; // HTTPS URL to the running preview when applicable
created_at: string; // ISO 8601
last_active_at: string; // ISO 8601 — most recent observed activity
};
```
Sandboxes are ordered by `last_active_at` desc (server-side default).
## Errors [#errors]
| Code | HTTP | Cause |
| ---------------- | ---- | --------------------------- |
| `UNAUTHORIZED` | 401 | Missing/invalid/expired PAT |
| `RATE_LIMITED` | 429 | 60 req/min per PAT exceeded |
| `INTERNAL_ERROR` | 500 | Unexpected server error |
See [Errors](/web/api/errors) for retry guidance.
## CLI equivalent [#cli-equivalent]
```bash
mogplex sandboxes list # pretty table
mogplex sandboxes list --json # NDJSON
mogplex sandboxes list --repo --status running
```
`mogplex sandboxes stop ` is a placeholder until the v1 lifecycle routes
land. Today it points users at the web UI.
## Read next [#read-next]
* [Repos](/web/api/repos) — list `repo_id` values
* [Runs](/web/api/runs) — sandboxes are created/used as runs execute
# Working Requests (/web/api/working-requests)
Use this page when you need a real first request against hosted Mogplex, not
just a description of the route tree.
These examples are intentionally biased toward routes that are already useful in
scripts, internal tooling, or debugging.
## Before you start [#before-you-start]
Authenticate with a Mogplex personal access token:
```bash
export MOGPLEX_BASE_URL="https://www.mogplex.com"
export MOGPLEX_TOKEN="mog_..."
```
Then reuse the same header everywhere:
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/auth/user"
```
These examples assume PAT auth. If you are trying to manage browser-only
account credentials such as token-management routes, read
[Authentication](/web/api/authentication) first because some endpoints
intentionally require a real session.
## 1. Check setup state with `GET /api/auth/user` [#1-check-setup-state-with-get-apiauthuser]
This is the best first call when you need to know whether the account is
actually ready.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/auth/user"
```
Representative response:
```json
{
"user": {
"id": "profile_123",
"email": "you@example.com",
"github_username": "octocat",
"github_state": "app_installed_with_synced_repos",
"github_installation_count": 2,
"github_covered_repo_count": 8,
"platform_access": {
"allowPlatformAi": true,
"allowPlatformSandbox": false
},
"vercel": {
"platformState": "ready",
"personalState": "linked",
"linkedProjectState": "repo",
"statusLabel": "Platform ready"
}
}
}
```
Current API field names still use `platform_access` and `allowPlatform*`.
Treat those fields as the route's managed account-access flags.
Use this call to answer:
* is the caller authenticated?
* is GitHub only OAuth-connected, install-pending, or fully App-covered?
* does the account have managed model and sandbox access?
* is optional Vercel project metadata already attached to a repo or project?
## 2. Read or update shared defaults with `/api/settings` [#2-read-or-update-shared-defaults-with-apisettings]
Read the current defaults:
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/settings"
```
Representative response:
```json
{
"default_model": "your-enabled-model-id",
"theme": "dark"
}
```
Update one field at a time with `PATCH`:
```bash
curl -sS \
-X PATCH \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"theme":"light"}' \
"$MOGPLEX_BASE_URL/api/settings"
```
Representative success response:
```json
{
"ok": true
}
```
Two practical details matter:
* invalid or unavailable default models return a `400`
* token-management routes under `/api/settings/*` are more sensitive than the
main settings route, so do not assume every settings endpoint has the same
auth policy
If you need the full model catalog or per-user enabled model set, switch to
[Models](/web/api/models). `/api/settings` only covers the selected
`default_model`, not the broader model list.
## 3. Inspect GitHub App coverage with `GET /api/github/installations` [#3-inspect-github-app-coverage-with-get-apigithubinstallations]
This is the first call to make when the browser can see repos but Triggers or
Automations still look empty.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/github/installations"
```
Representative response excerpt:
```json
[
{
"installation_id": 123456,
"account_login": "acme",
"scope_label": "Org",
"repository_count": 12,
"repositories": [
{ "id": "repo_1", "full_name": "acme/api" },
{ "id": "repo_2", "full_name": "acme/web" }
],
"manage_url": "https://github.com/organizations/acme/settings/installations/123456"
}
]
```
This is the route that tells you whether Mogplex has actual installation-backed
coverage, not just OAuth visibility.
## 4. Export CLI-ready MCP config with `GET /api/mcp-servers?format=cli` [#4-export-cli-ready-mcp-config-with-get-apimcp-serversformatcli]
This route is intentionally shared between the hosted control plane and the
CLI.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/mcp-servers?format=cli"
```
Representative response excerpt:
```json
[
{
"name": "sentry",
"enabled": true,
"config": {
"url": "https://mcp.sentry.dev",
"http_headers": {
"Authorization": "Bearer ..."
}
}
}
]
```
Two important behaviors to know:
* custom MCP servers win on name collision
* enabled MCP connections can also appear here, merged into the CLI-shaped
response
## 5. Create a workflow shell with `POST /api/flows` [#5-create-a-workflow-shell-with-post-apiflows]
Use this when you need a new automation shell for a GitHub App installation.
```bash
curl -sS \
-X POST \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
-H "Content-Type: application/json" \
-d '{"installation_id":123456,"name":"PR review graph"}' \
"$MOGPLEX_BASE_URL/api/flows"
```
Practical rules:
* `installation_id` is required
* the route returns `201` with the created flow object on success
* invalid or inaccessible installation ids return a typed flow-service error
instead of a generic success shape
If you only need one event to wake one agent, stop and use
[Triggers](/web/triggers) instead of scripting flows directly.
## 6. Pull runtime summary with `GET /api/observability/stats` [#6-pull-runtime-summary-with-get-apiobservabilitystats]
This is the best first call when you need a compressed “is the system healthy?”
read without loading every event row.
```bash
curl -sS \
-H "Authorization: Bearer $MOGPLEX_TOKEN" \
"$MOGPLEX_BASE_URL/api/observability/stats"
```
Representative response excerpt:
```json
{
"summary": {
"total_calls": 248,
"success_rate": 97.2,
"cost_today_estimate": 3.48,
"sandbox_active": 1,
"job_runs_pending": 2,
"job_runs_failed_24h": 1,
"suppressed_24h": 0,
"limit_denied_24h": 3
},
"by_model": [
{ "model": "your-enabled-model-id", "count": 190, "tokens": 1820342 }
],
"by_type": [
{ "type": "chat", "count": 220 }
]
}
```
This route is useful when you want summary cost, pressure, success rate,
sandbox activity, and model mix before drilling into detailed calls or jobs.
## A good first-day API sequence [#a-good-first-day-api-sequence]
If you are starting cold, use this order:
1. `GET /api/auth/user` to verify caller readiness
2. `GET /api/settings` to read shared defaults
3. `GET /api/models` if model availability or default resolution is part of the setup question
4. `GET /api/github/installations` to confirm App coverage
5. `GET /api/mcp-servers?format=cli` if the CLI should mirror hosted tools
6. `GET /api/observability/stats` once work is actually running
## Read next [#read-next]
* [Authentication](/web/api/authentication) for auth-path rules and session-only
nuance
* [Models](/web/api/models) for the standalone model route and preference writes
* [Route Families](/web/api/route-families) for the broader control-plane map
# Agent Roles (/web/automations/agent-roles)
Every automation agent node has a role.
That role is not cosmetic. It changes the operating expectation for the node
and helps the flow editor default to the right behavior.
## The three roles [#the-three-roles]
| Role | What it should do | Best starting events | What it should not be |
| -------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------ |
| `triage` | Read the event or thread, classify it, respond, or decide what happens next | `mention`, `issue_opened`, `issue_comment` | A code-review surrogate |
| `review` | Inspect changes and produce findings about correctness, security, regressions, or risk | `pr_opened`, `pr_comment`, `push`, `ci_failure` | A generic discussion bot |
| `edit` | Apply code changes after an earlier step already decided that mutation should happen | Follow-up node after `review` or a decision branch | A first-pass analyzer |
## Use `triage` for response and routing [#use-triage-for-response-and-routing]
`triage` is the right role when the agent should understand context before it
acts.
Typical cases:
* a GitHub mention asks for help on an issue or PR thread
* a new issue should be classified and given next steps
* an issue comment should wake a repo assistant and continue the conversation
Think of `triage` as “understand the event, then steer.”
## Use `review` for findings [#use-review-for-findings]
`review` is the right role when the agent should inspect code or diffs and
report what is wrong or risky.
Typical cases:
* a PR opens and should get structured review findings
* a push hits the default branch and should be reviewed
* a CI failure should trigger code-oriented analysis
This is also the only role that exposes auto-fix behavior in the current flow
editor.
## Use `edit` for explicit mutation [#use-edit-for-explicit-mutation]
`edit` is the role you use after the graph has already decided to change code.
That usually means:
* a `review` node found material issues
* a condition node determined a fix path should run
* you want the mutation step to stay explicit and isolated
This keeps analysis and mutation separate, which makes the graph easier to
debug and safer to reason about.
## Default role mapping [#default-role-mapping]
When you add a new agent node, Mogplex chooses a default role based on the
start event:
* `triage` for `mention`, `issue_opened`, and `issue_comment`
* `review` for `pr_opened`, `pr_comment`, `push`, and `ci_failure`
That default is a starting point, not a rule, but it captures the intended
product model.
## The common mistake [#the-common-mistake]
The most common mistake is using `review` for work that is really thread or
issue response.
If the main question is “what is happening here and what should happen next,”
that is usually `triage`.
If the main question is “what is wrong with these changes,” that is usually
`review`.
## Good starter patterns [#good-starter-patterns]
* `mention` -> `triage` -> condition -> follow-up response or end
* `issue_opened` -> `triage` -> parallel specialist agents -> join
* `pr_opened` -> `review` -> condition -> `edit`
* `ci_failure` -> `review` -> condition -> `edit` or human follow-up
# Overview (/web/automations)
Automations are the workflow graph surface in the web app.
Use them when one GitHub event should lead to multiple steps, branches, or
publish-controlled behavior instead of a simple one-event-to-one-agent route.
## Why you move up to Automations [#why-you-move-up-to-automations]
Automations exists for the moment when simple routing stops being enough.
If you need to say any of these, you are in automation territory:
* “only do the edit if the review node found a real issue”
* “split this work across multiple agents and join it later”
* “hold the route as a draft until we publish”
* “delay the next step until later”
## In this section [#in-this-section]
* [Agent Roles](/web/automations/agent-roles) for the exact difference between
`triage`, `review`, and `edit`
* [Publishing and Routing](/web/automations/publishing-and-routing) for draft
vs published behavior, activation, and the webhook routing model
## Mental model [#mental-model]
Each automation is installation-scoped and starts from exactly one GitHub event
on the start node.
From there the graph fans out through the canvas.
Current node types include:
* **Agent** nodes for `review`, `edit`, or `triage` work
* **Condition** nodes for true/false branching on event data
* **Parallel split** and **Join** nodes for fan-out and fan-in
* **Delay** nodes for scheduled waits inside the workflow
Two implementation details matter in practice:
* Agent-node overrides only change that node inside the current automation.
They do not mutate the base agent in [Agents](/web/agents).
* For `@mention` automations, Mogplex routes targeted mentions against the
**entry agent slug**. That means the slug on an agent node connected directly
to the start node, not a later downstream node.
This is the key split:
* [Agents](/web/agents) owns reusable definitions
* Automations owns orchestration around those definitions
## What the editor gives you beyond simple routing [#what-the-editor-gives-you-beyond-simple-routing]
The automation editor is more than a canvas.
It also gives you:
* draft editing with autosave
* manual save when you want an explicit checkpoint
* publish and activate controls separate from drafting
* duplicate, pause, and delete actions
* recent runs for the selected automation
* assistant-generated graph suggestions you can apply back into the draft
That combination is the main reason to choose Automations over
[Triggers](/web/triggers).
## Build from the start node outward [#build-from-the-start-node-outward]
The cleanest way to author an automation is:
1. pick the start event first
2. define the first agent role correctly
3. add conditions, delays, or parallel branches only where they change the
outcome
4. publish only when the draft matches the route you want live
Most workflow confusion comes from choosing the graph shape too early before the
entry event and entry role are actually clear.
## Pick the Right Agent Role [#pick-the-right-agent-role]
The role on an agent node changes how Mogplex expects that node to behave.
| Role | Use it when | Best entry events | Special behavior |
| -------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `triage` | The agent should read the event or thread, classify it, answer, label, or decide what happens next | `mention`, `issue_opened`, `issue_comment` | Best for conversational or operational response work. No review autofix behavior. |
| `review` | The agent should inspect code changes and report findings | `pr_opened`, `pr_comment`, `push`, `ci_failure` | Can emit structured review findings. This is the only role that exposes auto-fix in the flow editor. |
| `edit` | The graph has already decided to mutate code and this node should apply the change | Follow-up step after `review` or a condition branch | Use it as an explicit mutation step instead of overloading a reviewer. |
Mogplex also picks a default role when you insert a new agent node:
* `triage` for `mention`, `issue_opened`, and `issue_comment`
* `review` for `pr_opened`, `pr_comment`, `push`, and `ci_failure`
## Triage vs Review [#triage-vs-review]
This is the most common point of confusion.
Use `triage` when the agent should understand context first and respond in the
language of the thread or event. Typical cases:
* a GitHub mention asking for help on a PR thread
* a new issue that needs labeling, reproduction guidance, or next steps
* an issue comment that should wake a repo assistant and continue the
conversation
Use `review` when the agent should inspect changed code and produce findings
about it. Typical cases:
* a pull request opens and you want review comments
* a push lands on the default branch and you want a branch-level review
* a CI failure should trigger code-oriented analysis before a fix step
Use `edit` when you want the graph to apply changes only after an earlier node
has already decided that code should be mutated.
## Mention routing [#mention-routing]
Mention-driven automations use exact GitHub comment syntax.
* `@mogplex` creates a bare `mention` event
* `@mogplex/` creates a targeted `mention` event
Example:
```text
@mogplex/triage summarize this issue and suggest the next step.
```
Rules:
* Bare `@mogplex` only routes to mention automations whose start node is marked
**Default mention target**.
* Targeted mentions only route to mention automations whose entry agent slug
matches the text after `/`.
* The slash matters. `@mogplex triage` is just a bare mention plus text, not a
targeted mention.
* PR or issue comments without `@mogplex` use the `pr_comment` or
`issue_comment` event types instead of `mention`.
For the exact mention rules across Triggers and Automations, see
[GitHub Mention Routing](/web/guides/github-mention-routing).
## Drafting and publish lifecycle [#drafting-and-publish-lifecycle]
Automations keep a draft graph, autosave as you edit, and expose a separate
publish step.
Publishing does two things:
* saves the latest workflow version
* activates webhook routing against the published version
That lets you keep changing a draft without immediately changing live routing.
If an automation already has a published version, draft edits stay local to the
editor until you publish again. That separation is what makes the canvas safe
for iterative changes on a live route.
## Good starter patterns [#good-starter-patterns]
* `pr_opened` -> `review` -> condition -> `edit` or end
* `issue_opened` -> `triage` -> condition -> parallel follow-up agents
* `mention` -> `triage` -> delay -> follow-up response
These patterns are intentionally small. If you cannot explain the workflow in
one sentence, sketch the sentence before you sketch the graph.
## Getting started [#getting-started]
1. Connect GitHub and make sure the repo owner is covered by a GitHub App
installation.
2. Open the Automations canvas and create a flow for the installation you want.
3. Pick the start event first, then choose the role for each entry agent.
4. If the start event is `@mention`, decide whether this should be the default
mention target or a slug-targeted route.
5. Publish the automation when the draft is ready.
## What a healthy automation setup looks like [#what-a-healthy-automation-setup-looks-like]
* the installation you need is available
* the start event is explicit
* the entry agent role matches the job
* node-level overrides are deliberate, not accidental
* the published version is the one you actually intend to run
## Use Automations vs Triggers [#use-automations-vs-triggers]
Use [Triggers](/web/triggers) when one GitHub event should wake one agent with
minimal setup.
Use Automations when you need branching, parallel work, delays, draft/publish
separation, or a workflow that spans multiple steps.
# Publishing and Routing (/web/automations/publishing-and-routing)
Automations are not live-edit graphs.
Mogplex keeps a draft version you can keep changing, and a published version
that webhook routing actually uses.
## Draft vs published [#draft-vs-published]
Each automation stores:
* a draft graph you are actively editing
* a published version id that points at the live graph
Webhook routing does not read the draft. It routes against the published
version.
That separation is why the surface can support real editing without changing
production behavior on every drag or prompt tweak.
## What publish does [#what-publish-does]
When you publish an automation, Mogplex:
1. validates the draft graph
2. creates a new immutable `flow_version`
3. points `published_version_id` at that version
4. marks the flow `active`
That means the current product behavior is effectively “publish and activate,”
not “publish silently and maybe activate later.”
If a flow is already active, publishing replaces the live routing target with
the newest published version.
## What must be true before publish [#what-must-be-true-before-publish]
A publish can fail if the draft is not valid.
The important checks are:
* the graph is structurally valid
* agent ids in the graph belong to the current user
* the flow can be coerced into a valid start-to-end automation graph
This is intentional. Mogplex treats live routing as a controlled surface, not a
best-effort sketchpad.
## Activation [#activation]
An automation can also be toggled between `active` and `inactive`.
But a flow cannot be activated unless it already has a published version.
So the lifecycle is:
1. edit draft
2. publish
3. run live
4. optionally deactivate without discarding the published version
## Installation-scoped routing [#installation-scoped-routing]
Automations are installation-scoped.
That means the GitHub App installation is part of the routing key. A flow only
receives events for the installation it is attached to.
This is why installation coverage matters so much in setup: a perfect graph
still will not run if the GitHub App installation is wrong or missing.
## Event matching [#event-matching]
For normal events, matching is straightforward:
* the webhook event becomes a Mogplex trigger event
* Mogplex checks the published flow's start node event
* matching flows are enqueued
For `mention` events there is an extra rule:
* bare `@mogplex` only matches published mention flows marked default
* `@mogplex/` only matches published mention flows whose entry
agent slug matches the targeted slug
The published version is the source of truth here too.
## Operational implication [#operational-implication]
If you edit a mention flow in draft but do not publish it, GitHub is still
routing against the older published version.
That is the right behavior for production safety, but it is easy to forget
during testing.
## Recommended workflow [#recommended-workflow]
1. build the graph in draft
2. verify the start event and entry agents first
3. publish once the routing shape is intentional
4. test with the exact GitHub event you expect
5. use [Observability](/web/observability) to confirm the published graph is
the one actually receiving events
# Flows (/web/flows)
The legacy `/flows` route now redirects to `/automations`.
Use [Automations](/web/automations) for the current workflow builder.
## The naming changed, the runtime mostly did not [#the-naming-changed-the-runtime-mostly-did-not]
The original flow builder grew into a broader automation surface, so the UI and
docs now use **Automations** as the product term.
But the implementation still uses **flow** in several places.
That is why users can still run into both names at once.
## Legacy term vs current meaning [#legacy-term-vs-current-meaning]
| Legacy term | What it means now | Where you may still see it |
| ------------ | ----------------------------- | -------------------------------------------------------------------------- |
| flow | automation | `/api/flows`, internal types, some run metadata, and backend tables |
| flow version | published automation snapshot | publish lifecycle, stored versions, routing against `published_version_id` |
| flow run | automation run | run details and observability-backed execution records |
If you are reading logs, API routes, or internal references, mentally translate
`flow` to `automation`.
## What moved with it [#what-moved-with-it]
Everything that used to belong to the flow-builder path now lives in the
Automations surface, including:
* GitHub event entrypoints
* agent steps
* condition nodes
* parallel split and join nodes
* delay nodes
* notes and workflow description on the canvas
* draft editing, publish, and activation flow
* recent automation runs
* assistant-guided workflow suggestions
## Why the old term still matters [#why-the-old-term-still-matters]
Even though the route changed, the older term is still operationally relevant.
You may still see it when you:
* call or inspect `/api/flows`
* debug publish behavior that creates a new flow version
* read implementation details that talk about `flows` and `flow_versions`
* inspect webhook routing or run records that still key off a `flow_id`
So the product language is newer than the storage and API language.
That is not a contradiction. It is just the current state of the system.
## Current mental model [#current-mental-model]
Use [Automations](/web/automations) when one GitHub event should fan into a
multi-step workflow with branching or staged execution.
Use [Triggers](/web/triggers) when you only need a direct event-to-agent wakeup
without the automation canvas.
## How to read older references [#how-to-read-older-references]
If you find an older link, API example, or implementation note that still says
`flow`, read it like this:
* `flow` means the automation itself
* `flow version` means the published snapshot webhook routing uses
* `flow run` means one execution of that automation
That translation is usually enough to make old and new references line up.
## Getting the current docs [#getting-the-current-docs]
For live behavior, use:
* [Automations](/web/automations)
* [Agent Roles](/web/automations/agent-roles)
* [Publishing and Routing](/web/automations/publishing-and-routing)
* [GitHub Mention Routing](/web/guides/github-mention-routing)
This page stays in place so older bookmarks and links still land on the current
documentation path.
# Choose the Right Routing Surface (/web/guides/choose-routing-surface)
Mogplex has three routing surfaces on purpose:
* [Triggers](/web/triggers)
* [Assignments](/web/assignments)
* [Automations](/web/automations)
They overlap a little, but they are not the same tool.
## Before you choose anything [#before-you-choose-anything]
Answer these questions first:
1. is the source of truth a GitHub App installation event, one repo, or a
workflow graph?
2. does the repo owner already have GitHub App coverage, or is it only synced
through OAuth?
3. do you need draft and publish control, or should the route be live as soon
as it is created?
4. is this standing responsibility for one repo, or policy for an installation?
If those answers are fuzzy, the route choice will feel fuzzy too.
## Fast decision table [#fast-decision-table]
| Surface | Source of truth | Scope | Requires | Best fit | It is the wrong tool when |
| ------------------------------- | ---------------------------------------- | ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Triggers](/web/triggers) | One GitHub event | Installation-scoped | GitHub App coverage on the installation | One event should wake one agent with minimal ceremony | You need branching, publish control, or repo-owned standing work |
| [Assignments](/web/assignments) | One repo and one standing responsibility | Repo-scoped | The repo is imported and you know which agent should own the work | Durable PR review, push review, issue triage, CI failure, or cron work for one repo | The rule should apply at the installation event layer or needs a workflow graph |
| [Automations](/web/automations) | One GitHub event that becomes a graph | Installation-scoped | GitHub App coverage plus a published workflow | Branching, delays, parallel steps, conditional logic, and draft vs published behavior | One event simply needs one agent |
## Use Triggers when the rule is event -> agent [#use-triggers-when-the-rule-is-event---agent]
Pick [Triggers](/web/triggers) when one GitHub event should wake one agent with
minimal ceremony.
Good examples:
* PR opened -> review agent
* CI failure -> triage agent
* `@mention` -> default repo assistant
Use Triggers when you want the smallest routing surface that still works.
Two prerequisite details matter:
* Triggers are installation-scoped, so GitHub App coverage is required.
* Seeing a repo in [Projects](/web/spaces) is not enough if that repo is only
synced through OAuth.
If the trigger form has no usable installations, stop and fix App coverage
before debugging the agent.
## Use Assignments when the rule is repo -> agent [#use-assignments-when-the-rule-is-repo---agent]
Pick [Assignments](/web/assignments) when the repo is the durable unit of
routing and you want recurring operational behavior attached to that repo.
Good examples:
* one standing PR review agent for a repo
* a cron refactor or maintenance job
* a repo-specific issue triage or CI failure policy
Assignments are about durable responsibility, not just webhook entrypoints.
Two scope details matter:
* Assignments are repo-scoped, not installation-scoped.
* If you choose a built-in preset agent, Mogplex resolves it to an owned agent
for the assignment, reusing an existing fork when one exists or creating a
fork automatically.
That is why Assignments is the right surface when you want one repo to own a
standing contract instead of one installation to own an event rule.
## Use Automations when the rule is workflow -> graph [#use-automations-when-the-rule-is-workflow---graph]
Pick [Automations](/web/automations) when one event should lead to multiple
steps, branches, or gated decisions.
Good examples:
* split a PR event into two parallel review agents and join the result
* run one agent only when a condition on the event payload is true
* insert a delay before a follow-up step
* keep a draft workflow separate from the currently published version
If you need branching, publish control, or a workflow that spans multiple
steps, use Automations.
The setup nuance is the same as Triggers: Automations are installation-scoped
and need GitHub App coverage, not just synced repos.
The operating nuance is different: the draft graph is not the live route until
you publish it.
## Simple decision rule [#simple-decision-rule]
Use the lightest surface that fits:
1. one event to one agent: **Triggers**
2. one repo to one repeatable responsibility: **Assignments**
3. one event to a multi-step graph: **Automations**
## What people usually get wrong [#what-people-usually-get-wrong]
* A repo appearing in [Projects](/web/spaces) does not guarantee it can back a
Trigger or Automation. App coverage still has to exist.
* If the durable unit is the repo, not the installation, the route usually
belongs in [Assignments](/web/assignments), even if the event is “PR opened”
or “CI failure”.
* If you need draft editing and publish control, you are already in
[Automations](/web/automations), not Triggers.
* If the route can be explained as one event to one agent, Automations is
usually overbuilt.
## After routing starts [#after-routing-starts]
Once work is running, switch to [Observability](/web/observability).
That is the common runtime surface for all three routing models.
# Connection Scope and Overrides (/web/guides/connection-scope-and-overrides)
Connections in Mogplex are not just account-wide settings.
They resolve at two levels:
* **Global** connections are available everywhere by default.
* **Project** connections only exist for one repo.
On top of that, a repo can explicitly **exclude** a global connection without
deleting it for the rest of the account.
That split is what lets one repo use a tightly scoped toolset without forcing
the same choice on every other repo you work on.
## The model in one table [#the-model-in-one-table]
| Scope | Where you usually create it | What it applies to | Best fit |
| ---------------------------------- | --------------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------- |
| Global | [Settings](/web/settings) or the general Connections pane | Every repo unless one repo excludes it | Shared integrations you want almost everywhere |
| Project (`This Project` in the UI) | The Connections pane while a repo is active | One repo only | Repo-specific tools, credentials, or experimental integrations |
| Exclusion override | The Connections pane while a repo is active | Removes one global connection from one repo | Preventing a shared connection from appearing in the wrong repo |
## Where each connection surface lives [#where-each-connection-surface-lives]
Use [Settings](/web/settings) when you want to:
* connect a provider for the first time
* run the initial health check
* manage account-wide REST or MCP defaults
* reconnect OAuth-backed integrations
Use the repo-aware Connections pane inside a workspace when you want to:
* add a connection only for the active repo
* see the resolved connection set for that repo
* exclude one global connection from that repo
* confirm the repo-specific MCP count after overrides are applied
The practical rule is:
configure the integration in Settings first when you are onboarding it, then
switch to the repo context only if one project should behave differently.
## How resolution works inside a repo [#how-resolution-works-inside-a-repo]
When Mogplex resolves runnable connections for a repo, it effectively applies
this sequence:
1. start with enabled global connections
2. remove any global connections this repo has explicitly excluded
3. add enabled project-scoped connections that belong to the repo
That resolved set is what the active repo can actually use.
This matters most for MCP servers. The MCP limit is enforced against the
**resolved runnable set for that repo**, not just the raw account-wide list.
So if one repo is already dense with project MCPs, excluding a noisy global MCP
can be the difference between a clean tool surface and an overstuffed one.
## Choose Global vs Project on purpose [#choose-global-vs-project-on-purpose]
Choose **Global** when:
* the same integration should be available to most repos
* the credential or base URL is shared account-wide
* you want one place to reconnect or disable the integration
Choose **Project** when:
* only one repo should see that tool
* one repo needs different credentials or a different endpoint
* you are testing a tool without exposing it everywhere
* the connection only makes sense for one codebase or environment
Use an **exclusion override** when:
* the connection is still useful globally
* one repo should not see it
* you do not want to fork or duplicate the connection just to remove it from
one place
## Common examples [#common-examples]
### One shared MCP for most repos [#one-shared-mcp-for-most-repos]
If you use one Sentry or Linear connection almost everywhere, keep it global.
Then only exclude it in the repo where it would be distracting, wrong, or
unsafe.
### One repo talks to a different environment [#one-repo-talks-to-a-different-environment]
If one repo must call a staging-only REST API or a different MCP endpoint,
create that connection as **Project** scope from the active repo context.
That keeps the alternate credential or base URL from leaking into unrelated
repos.
### One repo should not inherit a noisy shared tool [#one-repo-should-not-inherit-a-noisy-shared-tool]
If you have a global MCP connection but a particular repo should stay lean,
exclude the global connection there instead of deleting it everywhere.
## Healthy operating sequence [#healthy-operating-sequence]
1. Add or reconnect the integration in [Settings](/web/settings).
2. Test it there until the connection itself is healthy.
3. Open the target repo workspace.
4. Decide whether the repo should inherit the global connection, exclude it, or
add a repo-only one.
5. Re-check the repo-scoped connection list before debugging prompts or routing.
That order matters because connection-health problems and scope problems are not
the same bug.
## What usually confuses people [#what-usually-confuses-people]
* A connection can be healthy in Settings and still be intentionally absent in
one repo because that repo excluded it.
* A project-scoped connection is not broken if it does not appear in other
repos. That is the point.
* Seeing a global connection in the account list does not mean it is part of
the resolved runnable set for every repo.
## Read next [#read-next]
* [Connections and MCP](/configure-and-extend/connections-and-mcp) for the
full connection and MCP operating model
* [Settings](/web/settings) for the account-level connections surface
* [Project Workflow](/web/guides/project-workflow) for the order of GitHub,
Projects, sandboxes, and repo setup
* [Working Requests](/web/api/working-requests) if you need to inspect the
underlying control-plane routes
# GitHub App Coverage (/web/guides/github-app-coverage)
Most confusion in Mogplex setup comes from mixing up two different GitHub
states:
* **GitHub connected** through OAuth
* **GitHub App installed** for the account or org that owns the repo
They are related, but they do different jobs.
## OAuth vs App coverage [#oauth-vs-app-coverage]
GitHub OAuth gives Mogplex your user identity and basic account connection.
GitHub App coverage determines which repos Mogplex can treat as triggerable for
webhook-backed work such as [Triggers](/web/triggers) and
[Automations](/web/automations).
That means a repo can be visible in [Projects](/web/spaces) but still not be
usable for triggered routing if the App is not installed for that owner.
## Common symptoms of missing App coverage [#common-symptoms-of-missing-app-coverage]
* Triggers is empty even though GitHub is connected
* Automations cannot find the installation or repo you expect
* A repo appears in Projects, but GitHub-backed routing is unavailable
* Settings shows GitHub connected, but installation coverage is missing or for
the wrong owner
## How to verify coverage [#how-to-verify-coverage]
Start in [Settings](/web/settings).
Check the GitHub App coverage and installation area. You want to verify:
* the installation belongs to the correct account or org
* the repo count and synced repo count look reasonable
* the repo owner you care about appears under an installation
If installation metadata is available, use the manage link back to GitHub to
confirm the App is installed where you think it is.
## What to do next [#what-to-do-next]
If GitHub is connected but the App is not installed for the repo owner:
1. Install the Mogplex GitHub App for that owner
2. Return to [Settings](/web/settings) and refresh the installation state
3. Go back to [Projects](/web/spaces) and sync repos again
4. Re-check [Triggers](/web/triggers) or [Automations](/web/automations)
## Rule of thumb [#rule-of-thumb]
If the question is "why can Mogplex see this repo but not route webhook work
for it?", the answer is usually App coverage, not OAuth.
# GitHub Mention Routing (/web/guides/github-mention-routing)
If you want Mogplex to wake a specific agent from GitHub, the mention syntax
has to be exact.
## Two different mention forms [#two-different-mention-forms]
Mogplex recognizes two forms:
* `@mogplex`
* `@mogplex/`
They do different things.
## Bare vs Targeted Mentions [#bare-vs-targeted-mentions]
### `@mogplex` [#mogplex]
This is a bare mention.
It only routes to mention handlers marked as the default target for that
installation:
* a mention [Trigger](/web/triggers) marked default
* a mention [Automation](/web/automations) whose start node is marked
**Default mention target**
### `@mogplex/` [#mogplexagent-slug]
This is a targeted mention.
It routes by agent slug instead of by the default flag.
Example:
```text
@mogplex/triage summarize this issue and suggest the next action.
```
If the slug is `triage`, that targeted mention is what wakes the matching
trigger or mention-entry automation.
## The Slash Matters [#the-slash-matters]
These are not equivalent:
* `@mogplex/triage`
* `@mogplex triage`
Only the first one is a targeted mention.
The second one is a bare `@mogplex` mention followed by normal text.
## Where Mentions Are Recognized [#where-mentions-are-recognized]
Mention routing comes from GitHub comments:
* issue comments
* PR conversation comments
* PR review comments
* commit comments
That means a mention in an issue title, issue body, or PR description is not
the same routing event as a GitHub comment mention.
## Using Mentions with Triggers [#using-mentions-with-triggers]
Use [Triggers](/web/triggers) when one mention should wake one agent.
The pattern is:
1. Create a trigger with the `@mention` event.
2. Choose the agent that should answer.
3. Mark it default if you want bare `@mogplex` mentions to hit it.
Use a targeted mention when you want to skip the default and call a specific
agent directly:
```text
@mogplex/triage please classify this bug and suggest the next step.
```
## Using Mentions with Automations [#using-mentions-with-automations]
Use [Automations](/web/automations) when one mention should kick off a graph.
The pattern is:
1. Set the start node event to `@mention`.
2. Connect the start node directly to the entry agent node.
3. Mark the start node default if bare `@mogplex` should wake this flow.
4. Use the entry agent slug for targeted mentions.
Important detail:
Targeted mention routing checks the slug on an **entry agent**, meaning an
agent connected directly to the start node. Downstream agents do not control
mention matching.
## Calling a Triage Agent [#calling-a-triage-agent]
If your mention-entry agent slug is `triage`, call it like this:
```text
@mogplex/triage read the full thread, summarize the problem, and suggest next steps.
```
Use bare `@mogplex` only when that triage route is the default mention target.
## Common Mistakes [#common-mistakes]
* Marking a mention route as default and then expecting `@mogplex/` to be
optional. It is not.
* Using the display name instead of the slug.
* Targeting a downstream automation node instead of the entry agent.
* Expecting PR or issue comments without `@mogplex` to use the `mention`
event. Those become `pr_comment` or `issue_comment` events instead.
## Rule of Thumb [#rule-of-thumb]
Use `@mogplex` for the one default assistant.
Use `@mogplex/` when you want to wake a specific agent on purpose.
# Overview (/web/guides)
Use these guides when you want the working sequence between product surfaces,
not just route-by-route descriptions.
## Start here if... [#start-here-if]
* you are setting up a repo for the first time:
[Project Workflow](/web/guides/project-workflow)
* you can see repos, but trigger-backed surfaces still look empty:
[GitHub App Coverage](/web/guides/github-app-coverage)
* one repo should have different tool access than the rest of your account:
[Connection Scope and Overrides](/web/guides/connection-scope-and-overrides)
* you are not sure whether the job belongs in Triggers, Assignments, or
Automations:
[Choose the Right Routing Surface](/web/guides/choose-routing-surface)
* mention routing is not behaving the way you expected:
[GitHub Mention Routing](/web/guides/github-mention-routing)
* older bookmarks or route names are confusing:
[Legacy Routes](/web/guides/legacy-routes)
## Use the guides differently from the route docs [#use-the-guides-differently-from-the-route-docs]
The route docs explain what each page is for.
These guides explain:
* which page to start from
* what prerequisite state must already exist
* what common failure mode to check next
* how to move between setup, routing, and runtime inspection without guessing
If you already know the surface you need, go back to the route docs.
If you know the problem but not the next page, start here.
# Legacy Routes (/web/guides/legacy-routes)
Older route names still appear in bookmarks, screenshots, logs, and internal
notes.
This page is the fast map from those older names to the current Mogplex
surfaces.
## Current redirect map [#current-redirect-map]
| Older route | Current destination | Best doc page |
| ------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `/flows` | `/automations` | [Flows](/web/flows) or [Automations](/web/automations) |
| `/library` | `/agents/skills` by default, with tab-specific redirects for rules, context, and models | [Library](/web/library) |
| `/primitives` | `/agents/skills` by default, with tab-specific redirects for rules and context | [Primitives](/web/primitives) |
## When the old route names still matter [#when-the-old-route-names-still-matter]
You will still run into these names when you:
* follow an old bookmark
* read implementation notes or screenshots from an earlier UI
* inspect logs or route traces that still use the older path
* compare the browser route with current docs and wonder whether the feature
moved
## How to read them now [#how-to-read-them-now]
### `/flows` [#flows]
The product surface is now **Automations**.
Use [Flows](/web/flows) when you need the naming translation, and use
[Automations](/web/automations) for live behavior.
### `/library` [#library]
The older library idea has been split by job:
* skills, rules, and context now live under [Agents](/web/agents)
* models now live under [Settings](/web/settings)
Use [Library](/web/library) when you need the tab-by-tab redirect map.
### `/primitives` [#primitives]
This route now forwards into the same agent-library surfaces, but it does not
own the models tab.
Use [Primitives](/web/primitives) for the exact redirect behavior.
## Related route-name mismatch [#related-route-name-mismatch]
The UI still says **Projects** even though the live route is `/spaces`.
For that translation, use:
* [Projects](/web/spaces) for the current live behavior
* [Projects (Legacy Docs Route)](/web/projects) if you landed on an older docs
link
## Practical rule [#practical-rule]
If you find an older Mogplex route in the wild, do not assume the feature was
removed.
Check whether it was renamed, split, or redirected before you treat it as dead.
# Project Workflow (/web/guides/project-workflow)
This is the cleanest first-run path when you are setting up Mogplex for a repo
or org for the first time.
The main thing to keep straight is that Mogplex separates three jobs:
* connecting your GitHub identity
* getting the right repos into Projects
* enabling the routing surface you actually want
If you do those in the right order, setup gets much easier to reason about.
## 1. Connect GitHub [#1-connect-github]
Start in [Settings](/web/settings) and connect GitHub.
That establishes your account identity and is enough to start importing repos.
It is **not** the same thing as GitHub App coverage.
That distinction matters because Mogplex treats these setup states
differently:
| State | What it unlocks | What it does not unlock yet |
| ---------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| Disconnected | Nothing GitHub-backed | Repo import, repo creation, trigger routing |
| OAuth connected | Repo import and repo creation | Webhook-backed routing |
| App install pending | Repo import can still work if OAuth is already connected | Trigger-ready coverage until the install completes |
| App installed, no synced repos yet | Installation coverage exists | Repos will not show up in Projects until they are synced or imported |
| App installed with synced repos | Full GitHub-backed setup | N/A |
If you only remember one rule, use this one:
* GitHub connection lets Mogplex see repos
* GitHub App coverage lets Mogplex route webhook-backed work into them
## 2. Confirm App coverage [#2-confirm-app-coverage]
Still in [Settings](/web/settings), check the GitHub App coverage section and
the installation list.
You want to verify:
* the correct account or org is installed
* the installation lists the repos you care about
* Mogplex has started syncing covered repos into Projects
If that is not true yet, use the
[GitHub App Coverage](/web/guides/github-app-coverage) guide before going
further.
## 3. Create the project structure you actually want [#3-create-the-project-structure-you-actually-want]
Go to [Projects](/web/spaces).
Projects can be empty. You do not need to wait for a perfect import state
before organizing the workspace structure.
In practice, you usually choose one of these paths:
* keep using the default imported project for synced repos
* create additional projects to separate teams, products, or environments
* create a brand-new GitHub repo directly inside a project
Mogplex supports both imported repos and app-created repos, so "set up
Projects" is not the same thing as "sync everything first."
## 4. Import or create repos [#4-import-or-create-repos]
From [Projects](/web/spaces), you can:
* import repos into the default imported project
* create additional projects to group repos
* create a new GitHub repo inside a project when GitHub is already connected
* add sub-project repos for monorepo targets
* configure repo-specific settings such as sandbox behavior, env sync, and
linked Vercel project state
Two practical nuances matter here:
* If GitHub is connected through OAuth, you can still import repos before the
App install is finished.
* Once installation-backed sync is active, covered repos become the preferred
source of truth in Projects, which helps avoid stale OAuth-only duplicates.
## 5. Confirm managed sandbox access if you plan to launch workspaces [#5-confirm-managed-sandbox-access-if-you-plan-to-launch-workspaces]
Repo import and routing setup do not require sandbox access, but
sandbox-backed workspace sessions do.
Hosted sandbox access is billed through Mogplex. Users do not need to attach an
external sandbox account for workspace sessions.
If you only want to configure routing first, you can do that before the account
has managed sandbox access.
## 6. Open a workspace [#6-open-a-workspace]
From [Projects](/web/spaces), open a workspace session for the repo you want.
If a sandbox is not already running, Mogplex can launch one as part of opening
the workspace. This is the fastest route into active repo work.
That means the normal operator loop is:
1. import or create the repo
2. open the workspace
3. let Mogplex launch the sandbox if needed
4. start doing repo work from the session
This is also the point where repo-scoped controls become practical.
If one repo should use a different integration surface than the rest of your
account, open the repo-aware Connections pane and decide which tools stay
global, which should be excluded, and which belong only to that repo. See
[Connection Scope and Overrides](/web/guides/connection-scope-and-overrides).
## 7. Choose the routing model [#7-choose-the-routing-model]
Once the repo is imported, choose the lightest surface that matches the job:
* Use [Triggers](/web/triggers) for one event to one agent
* Use [Assignments](/web/assignments) for durable repo-to-agent routing such as
PR review, CI failure, or cron work
* Use [Automations](/web/automations) when you need branching, multiple steps,
or publish control
For webhook-backed routing, make sure the repo is App-covered, not just synced.
That is the most common setup miss when a repo looks available in Projects but
still will not wake Triggers or Automations.
## 8. Watch it in Observability [#8-watch-it-in-observability]
After work starts running, move to [Observability](/web/observability).
That is where you confirm run status, pressure, failures, call details, tool
usage, and sandbox-linked execution state.
## Fastest successful setup path [#fastest-successful-setup-path]
If you want the shortest version:
1. Connect GitHub in [Settings](/web/settings)
2. Install the GitHub App for the repo owner
3. Open [Projects](/web/spaces) and import or create the repo
4. Confirm managed sandbox access if you need sandbox-backed workspaces
5. Open a workspace
6. Add a Trigger, Assignment, or Automation
7. Test the exact GitHub event you expect, then confirm it in
[Observability](/web/observability)
# Coverage and Triggerability (/web/installations/coverage-and-triggerability)
Most setup confusion in Mogplex comes from mixing up three different states:
* GitHub account connected
* repo visible in Mogplex
* repo triggerable for webhook-backed work
Those are related, but they are not the same thing.
## OAuth is not enough [#oauth-is-not-enough]
GitHub OAuth can be enough to connect an account and discover repositories.
But webhook-backed routing depends on GitHub App coverage.
That means a repo can still:
* appear in [Projects](/web/spaces)
* belong to the right user
* even be synced already
and still not be eligible for [Triggers](/web/triggers) or
[Automations](/web/automations) if the GitHub App is not installed for the
owner that controls that repo.
## What "triggerable" actually means [#what-triggerable-actually-means]
Operationally, a repo becomes triggerable when Mogplex can associate it with a
real GitHub App installation id.
That installation id is the bridge between:
* GitHub webhook events
* synced repos in Mogplex
* installation-scoped routing surfaces
Without that bridge, Mogplex can see the repo but cannot safely route
App-backed automation into it.
## Two different state layers [#two-different-state-layers]
Mogplex exposes both a user-level GitHub state and a repo-level coverage state.
### User-level GitHub state [#user-level-github-state]
The account connection can show up in states like:
| State | Meaning |
| ----------------- | ------------------------------------------------------------------ |
| `OAuth only` | GitHub is connected, but routing still needs App coverage |
| `Install pending` | The App install was started, but GitHub still needs to finish it |
| `App installed` | Coverage exists, but no covered repos are synced into Projects yet |
| `Ready` | App coverage is active and covered repos are already synced |
These are account signals, not repo signals.
### Repo-level coverage state [#repo-level-coverage-state]
Each repo effectively falls into one of these buckets:
| Repo label | Meaning |
| --------------- | ----------------------------------------------------------------------------------- |
| `Trigger-ready` | The repo has a `github_installation_id` and can participate in App-backed routing |
| `Synced only` | The repo is visible in Projects, but has no App coverage yet |
| `Not covered` | The App is installed somewhere for the user, but not for this repo's owner or scope |
This is the state that matters when the question is "will this route wake up?"
## What the installations surface exposes [#what-the-installations-surface-exposes]
The installations data shown in [Settings](/web/settings) exists to answer a
very practical question:
"Which GitHub owner scopes are actually available for App-backed automation?"
Each installation surfaces:
* account or org login
* scope label such as `Org`, `User`, or `Account`
* synced repo count for the installation
* a GitHub manage link when the metadata is complete enough to build one
* the repos Mogplex currently associates with that installation
If installation metadata is incomplete, Mogplex will try to refresh it from
GitHub before presenting the final view.
## Reconciliation can fill in missing installation state [#reconciliation-can-fill-in-missing-installation-state]
Mogplex does not only rely on the user manually refreshing setup pages.
If the app has GitHub App config and knows your GitHub username, the hosted
surfaces can attempt to reconcile installation state when the current install
list is still empty.
That is why these pages can sometimes "heal" after an install finishes in
GitHub even if you did not manually resync every step yourself.
## Typical failure symptoms [#typical-failure-symptoms]
When coverage is missing or wrong, users usually see one of these:
* Triggers is empty
* Automations cannot find the installation they expect
* a repo shows up in Projects but cannot participate in webhook routing
* Settings says GitHub is connected, but the status is still `OAuth only`
* Settings shows an App installation, but the repo you care about is still
`Synced only` or `Not covered`
## Mental model [#mental-model]
Use this rule:
* OAuth answers "who are you?"
* installation coverage answers "which owners and repos can Mogplex automate?"
If the question is about routing, coverage is the thing that matters.
## Good troubleshooting order [#good-troubleshooting-order]
1. Check [Settings](/web/settings) and read the current GitHub status label
2. Confirm the expected owner or org appears in [Installations](/web/installations)
3. Check whether the repo is actually `Trigger-ready`, not just visible in
[Projects](/web/spaces)
4. If the App install recently changed, let Mogplex reconcile or rerun repo
sync
5. Retry the exact GitHub event you expect, then confirm it in
[Observability](/web/observability)
# Overview (/web/installations)
Installations are the GitHub App coverage layer behind Mogplex repo automation.
There is not a separate top-level `/installations` dashboard route today. This
docs section describes the GitHub App installation state surfaced in
[Settings](/web/settings) and consumed by [Projects](/web/spaces),
[Triggers](/web/triggers), and [Automations](/web/automations).
## The distinction to keep explicit [#the-distinction-to-keep-explicit]
For most setup problems, there are three states a repo can be in:
1. **not visible at all**
2. **visible through GitHub OAuth**
3. **covered by a Mogplex GitHub App installation**
Only the third state is fully eligible for App-backed routing and automation.
That is why Installations deserves its own docs section even though the product
does not currently expose it as a standalone top-level dashboard page.
## Why installations matter [#why-installations-matter]
An installation answers two different questions:
1. which account or org has granted the Mogplex GitHub App access
2. which repos are therefore eligible for App-backed behavior
That second point is the important one. A repo can be visible through OAuth and
still not be triggerable.
## OAuth vs installation coverage [#oauth-vs-installation-coverage]
Keep this distinction explicit:
* **GitHub OAuth** gives Mogplex an authenticated user identity and supports
repo discovery
* **GitHub App installation** gives Mogplex webhook-backed coverage for the
installed account or org
That is why a repo can appear in [Projects](/web/spaces) yet still fail to
participate in [Triggers](/web/triggers) or installation-backed automations.
## What “covered” unlocks in practice [#what-covered-unlocks-in-practice]
When the right installation exists, Mogplex can do more than just list repos.
It can:
* receive webhook events for the installed owner
* offer that installation as a routing target in [Triggers](/web/triggers)
* treat repos under that owner as eligible for App-backed workflows
* reconnect synced repos to the correct owner and installation metadata
## What the app surfaces show [#what-the-app-surfaces-show]
Inside [Settings](/web/settings), each installation can show:
* the account or org name
* whether the scope is personal or org
* the synced repos Mogplex currently associates with that installation
* how many repos are mapped to it
* a direct manage link back to GitHub
This is the fastest way to answer the real operator question:
**Do I have the right App installed on the right owner, or am I only seeing
repos through OAuth?**
## How Mogplex keeps installation state fresh [#how-mogplex-keeps-installation-state-fresh]
The installations API is a little self-healing.
If Mogplex has GitHub App config and your GitHub username, but there are no
stored installations yet, it can reconcile against GitHub again and hydrate the
local installation records before returning the Settings view.
It can also refresh incomplete installation metadata, such as missing account
login or target type, and then derive:
* a scope label like `Org` or `User`
* the GitHub manage URL for that installation
That is why the Settings page can often recover from stale installation records
without asking you to reconnect everything manually.
## The most reliable workflow [#the-most-reliable-workflow]
1. Connect GitHub in [Settings](/web/settings).
2. Confirm the expected personal account or org appears in the installation
list.
3. Sync repos into [Projects](/web/spaces).
4. Only after that, debug [Triggers](/web/triggers) or
[Automations](/web/automations).
If you skip step 2, you can spend time debugging a routing problem that is
really just missing GitHub App coverage.
## Common symptoms of missing coverage [#common-symptoms-of-missing-coverage]
* the repo appears in [Projects](/web/spaces), but [Triggers](/web/triggers)
offers no useful installations
* mention or PR-triggered work never fires even though the repo is visible
* webhook-backed automation looks empty or unavailable for the owner you need
* the app appears connected, but Mogplex still behaves as if the repo is
“outside” the GitHub App boundary
## In this section [#in-this-section]
* [Coverage and Triggerability](/web/installations/coverage-and-triggerability)
explains the “repo is visible but not triggerable” setup model
* [Repo Sync and Rebinding](/web/installations/repo-sync-and-rebinding)
explains how repos are attached to installations and how stale bindings get
repaired
## Where installations show up in the product [#where-installations-show-up-in-the-product]
* [Settings](/web/settings) is the main inspection surface
* [Projects](/web/spaces) shows the repos that were imported or synced
* [Triggers](/web/triggers) only offers installations that are actually
available for webhook-backed routing
* [Automations](/web/automations) depends on installation-backed GitHub events
If routing or review behavior looks wrong, check installation coverage before
you debug the agent or automation itself.
# Repo Sync and Rebinding (/web/installations/repo-sync-and-rebinding)
Installations are not just metadata rows.
They are part of the live routing model for repos, triggers, and automations.
That means sync has two jobs at once:
* keep the repo inventory accurate
* keep installation-scoped routing attached to the right installation id
## Installation-backed sync [#installation-backed-sync]
When GitHub App configuration is available, Mogplex prefers installation-scoped
repo sync.
That matters because installation-backed sync gives Mogplex a real
`github_installation_id` for the repo instead of just an OAuth-discovered repo
record.
In practice, that means covered repos become the preferred source of truth for
automation routing.
## OAuth sync vs installation sync [#oauth-sync-vs-installation-sync]
These paths look similar in the UI, but they behave differently:
| Sync path | What it does | What it avoids doing |
| ---------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| OAuth-only sync | Imports repos Mogplex can discover through the connected GitHub user | Does not overwrite an existing App installation id on a repo |
| Installation sync | Imports the repos GitHub says belong to a specific App installation and records that installation id | Does not guess across multiple installations |
| Webhook reconciliation | Reacts to install, uninstall, repo add/remove, rename, transfer, and delete events | Does not rely on manual resync to stay current |
That separation is deliberate. An OAuth import is useful for visibility, but it
is not allowed to silently clobber App-backed routing state.
## What Mogplex updates and what it preserves [#what-mogplex-updates-and-what-it-preserves]
During repo sync, Mogplex intentionally protects a few things:
* base repo rows are the sync target
* sub-project repos with a `root_directory` are not overwritten as if they were
standalone base repos
* GitHub metadata such as `full_name`, owner, repo name, and default branch
still propagates to matching sub-project rows
* an OAuth-only sync will not erase a stored `github_installation_id`
That combination lets Mogplex refresh repo identity without destroying monorepo
structure or installation coverage.
## Why this matters for Projects [#why-this-matters-for-projects]
Older OAuth-only repo rows can linger after a user moves to installation-backed
GitHub access.
When installation-backed sync is active, Mogplex prefers covered repos in
Projects so stale OAuth-only rows do not crowd the active list.
## Metadata refresh [#metadata-refresh]
If cached installation metadata is incomplete, Mogplex can refresh it from
GitHub and persist the missing account login, account type, target type, and
permissions.
That is why the installations view can improve after reconciliation even if the
underlying row started incomplete.
## What happens when installations change [#what-happens-when-installations-change]
When installation state changes from GitHub webhooks, Mogplex can:
* upsert installation rows
* resync repos for affected users
* add installation coverage to newly added repos
* detach repo installation ids if an installation or repo scope is removed
* delete repo rows when GitHub reports the repo itself was deleted
This keeps repo coverage aligned with the actual GitHub App state instead of
treating it as a one-time setup import.
The important webhook-backed update paths are:
* `installation` events such as create, permission change, unsuspend, delete,
and suspend
* `installation_repositories` events when repos are added to or removed from an
installation
* `repository` events such as create, rename, transfer, visibility changes, and
delete
## Rebinding stale trigger and automation state [#rebinding-stale-trigger-and-automation-state]
Automations and triggers are installation-scoped too.
So when repo coverage changes, stale installation bindings on automation
entities can become a problem.
Mogplex has a repair path for this during installation-backed sync:
* it loads the current installation ids known for the user
* it only proceeds if there is exactly one current installation
* it only proceeds if that installation matches the installation being synced
* it then updates stale automation and trigger installation ids to that current
one
This is deliberately conservative. Mogplex only does it when the installation
state is clear enough to avoid guessing wrong.
If a user currently has multiple installations, Mogplex skips the automatic
rebind instead of guessing which installation the stale routes should now point
at.
## The operational takeaway [#the-operational-takeaway]
If installation routing feels stale, do not only look at the automation or
trigger.
Also check:
* whether the repo is covered by the expected installation
* whether installation-backed repo sync has run recently
* whether the installation inventory is ambiguous for that user
The "repo looks fine but automation does not wake up" class of bug is often a
sync or binding problem, not a prompt problem.
## Good troubleshooting order [#good-troubleshooting-order]
1. Check [Settings](/web/settings) to confirm the right installation exists for
the repo owner
2. Check [Projects](/web/spaces) to confirm the repo is App-covered, not just
visible
3. Re-run repo sync if coverage recently changed
4. Re-test the exact GitHub event that should wake the route
5. Use [Observability](/web/observability) to confirm whether the event reached
the expected trigger or automation