A cloned project lives under ~/Documents/MainPath/<organization-slug>/<project-slug>/ with one folder per repository; a symlink to local-configuration places .vscode next to them. Open the project folder in your editor rather than a single repository; the layout in a remote workspace is identical.
Starting applications
Every application starts from the root of its repository with the same command:
mp run-local
A backend starts Docker services and dev server, an app Flutter Web or its stack’s dev server, a homepage Hugo or Astro, each with the env files and on fixed ports (mp ports). For Flutter you pass target and device, such as mp run-local chrome; --env dev loads the dev configuration instead of the local one, and MainPath extension’s start button runs the same command, see Starting applications.
Runtimes via asdf
Runtime versions are pinned per repository in .tool-versions; asdf manages them on macOS and Linux, FVM, NVM and HVM on Windows. mp bootstrap installs them without starting the application, mp doctor shows missing tools. Do not install runtimes globally around the project, or your machine builds differently than the pipeline.
Generated and custom files
MainPath writes env/*.generated.env and .gitlab-ci.yml and overwrites them whenever the project changes; your values go into env/*.custom.env, after which you restart mp run-local. A pre-commit hook (mp git pre-commit check) from the MainPath Toolbox and clone blocks commits to the generated files; the individual files and gitops-configuration for dev and prod are covered in Environment variables. MainPath manages passwords, tokens and keys encrypted; they do not belong in *.custom.env, commits, logs or chat replies.
Uploads in the backend
A backend stores persistent file uploads under ./upload locally and under /app/upload in the container, where the server mounts ./backend-uploads; Multer, FastAPI upload handlers or Laravel Storage point there and not at user-uploads or /app/uploads. Dockerfiles create the folder with RUN mkdir -p upload.
Rules for AI agents
The agent plugin (mp agent install) sums up these rules and requires working in the matching app repository, not in local-configuration. You add your own rules in an AGENTS.md in the application repository (Your own rules for AI agents); what the pipeline does after the push is covered in Git workflow and deployment.