Projects

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

• 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

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

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.

Repo settings you can control

The repo settings dialog has three tabs.

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

Use this tab when the repo needs GitHub secret configuration managed alongside its Mogplex setup.

Snapshot

Use this tab to inspect the repo snapshot state Mogplex is using for sandbox work.

A practical first workflow

1. Connect GitHub in Settings.
2. Confirm the right user or org has Mogplex GitHub App coverage in 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
   • add a Trigger when routing should be installation-wide
   • move to Automations for multi-step flows

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

Projects is where sandbox launch usually starts, but it is not the only sandbox surface.

Use 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

• 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

• Installations explains GitHub App coverage and repo triggerability.
• Assignments is for standing repo-to-agent work.
• Triggers is for installation-scoped event routing.
• Observability is where you inspect cost, calls, sandbox linkage, and runtime health after work starts.