# 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.