> ## Documentation Index > Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt > Use this file to discover all available pages before exploring further. # Lifecycle Setup > Set up how your project installs, builds, runs, and is health-checked — together with the agent in chat Every project needs a **Lifecycle Setup** - the scripts, environment variables, and documentation that define how the application installs dependencies, builds, runs, passes a health check, and tests. The Morph Platform uses this configuration to validate your setup, run functional tests, and verify milestone output. You don't fill this in with a form. The Morph Platform sets it up **with you in chat**, inside the **Project Knowledge** drawer, during the **Project Setup** stage of onboarding. The agent inspects your repository, proposes the scripts and variables, asks you for anything it can't infer, and runs the whole lifecycle end to end to prove it works. *** ## When Lifecycle Setup Happens **Project Setup** is a stage on the Roadmap onboarding checklist. It runs **after** you approve the Project Spec and choose a validation level: 1. **Setup Build Environment** 2. **Set Modernization Goals** 3. **Generate Project Spec** 4. **Approve Project Spec** 5. **Choose Validation Level** 6. **Project Setup** ← lifecycle setup happens here 7. **Generate Roadmap** ![Roadmap onboarding checklist with the Project Setup stage in progress](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/project-setup-stage.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=5ac2ceaca4754e74e676e319ad11133c) While the stage is running, the checklist shows it as **Setting up Project…**. > [!WARNING] > > **Project Setup only runs at the High [validation level](/setup/validation-level).** At Low and Mid, the Morph Platform skips origin lifecycle setup entirely — the origin application is never built or run, so there is nothing to configure. The target lifecycle is still discovered automatically during the foundation milestone. > > If you start at Low or Mid and later upgrade to High, the Morph Platform opens Project Setup at that point and runs the same chat flow. Clicking **Project Setup** opens the Project Knowledge drawer with Knowledge chat already started. The drawer also opens on its own the first time the stage becomes active. *** ## Setting Up the Lifecycle in Chat The first time you land in Project Setup, the drawer is **chat only** — there is no tree or content pane yet, because there is nothing to show until the agent discovers it. The chat opens on *"Welcome! Time to set up the project and get started"* and starts working. While the sandbox boots, the chat shows its progress: allocating resources, cloning the repository, installing dependencies, indexing project context. The tree and content pane appear alongside the chat as soon as the agent has something to put in them. ### What the agent works through The agent maintains a visible to-do list and works through it in order. Which items appear depends on your build environment: | Phase | When it runs | What happens | | - | - | - | | **Strategy** | Self-hosted only | Asks whether you or the Morph Platform will run the app — see [Lifecycle Strategy](/setup/lifecycle-strategy) | | **Dockerfile** | Modelcode Hosted | Builds the container image the project runs in | | **Dependencies** | Self-hosted | Resolves and installs the toolchain the project needs | | **Lifecycle** | Always | Discovers and validates the origin install / build / run / healthcheck / test scripts | | **Script discovery** | Optional | Finds extra named scripts (lint, coverage, and so on) that [acceptance criteria](/setup/acceptance-criteria) can read | | **Acceptance criteria** | Optional | Proposes quality gates from those scripts, then lets you add your own | Once the lifecycle validates, the agent asks a single question: whether you want to set up [acceptance criteria](/setup/acceptance-criteria). Answer **Skip — I'll do this later** and the last three phases are marked skipped and onboarding wraps up there; you can add scripts and criteria from the chat at any point afterwards. > [!NOTE] > > On a self-hosted project that uses the **connect** strategy, the **Dependencies** phase is skipped too — the Morph Platform isn't building or running the app, so there is no toolchain to resolve. For the lifecycle phase specifically, the agent: 1. **Inventories the repository** — framework, install/build/run commands, health-check signals, environment variables, external service dependencies — and reports what it found before writing anything. 2. **Proposes the phases** and confirms them with you. Beyond the standard five, this can include steps like `migrate` or per-service splits in multi-service projects. 3. **Registers the scripts and environment variables**, asking you for values it can't infer. 4. **Executes the lifecycle end to end** to prove it works. On failure it shows you the failing phase, the last lines of output, and a proposed fix before retrying. ![To-do progress chip and list showing the agent working through the setup phases](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/chat-discovery-progress.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=b62e2d2cadb91cc6195e18ade637f4d0) ### Answering the agent's questions The agent asks structured questions rather than free-text prompts wherever it can. Pick one of the options or write your own, then click **Submit**. **Skip** leaves the decision to the agent. ![Clarify card in Knowledge chat with a recommended option and an Other free-text choice](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/chat-clarify-card.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=9d61fbf7679ed99a281c7059037bfaa4) ### Providing secrets When the lifecycle needs a credential — an API key, a database password, a service token — the agent asks for it with a **Provide Secret** card instead of asking you to type it into the chat. The value is encrypted immediately and is never shown to the agent or written into the transcript. ![Provide Secret card with a masked value field and show/hide toggle](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/chat-provide-secret.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=988f4872741b3e85723f58d9980ddcab) > [!TIP] > > Never paste a secret into the chat message box. Use the **Provide Secret** card — anything typed into the chat becomes part of the conversation history. ### When setup finishes Once the lifecycle validates, the chat confirms it and onboarding continues to **Generate Roadmap**. If the agent can't get the application fully healthy, it asks you to confirm saving the configuration as a **Draft** so you can correct it yourself. *** ## The Project Setup Panel Once the lifecycle exists, the drawer switches to its full layout: a tree on the left, the selected content in the middle, and chat on the right. **Project Setup** is the branch of the tree that holds everything the Morph Platform needs to run your application. ![Project Setup tree and content panel in the Project Knowledge drawer](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/project-setup-panel.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=04ea6199932f63ee020b9e98a7d9a7d6) > [!TIP] > > Use **Hide chat** in the toolbar to collapse the chat column and give the content panel the full width — useful when you're reading a long lifecycle document. The branch is organized by side of the migration: ``` Project Setup ├── Origin │ ├── Scripts │ ├── Environment Variables │ └── Lifecycle Document ├── Target │ ├── Scripts │ ├── Environment Variables │ └── Lifecycle Document ├── Acceptance Criteria └── Dockerfile (Modelcode Hosted) / Dependencies (Self-hosted) ``` * **Origin** - How the source application builds and runs. Set up with you during Project Setup and used as the behavioral baseline for [functional testing](/migration/validation-hub). * **Target** - How the destination application builds and runs. Discovered automatically during the foundation milestone (Milestone 1). The **Target** entry stays disabled until then, with the tooltip *"Available once a target lifecycle configuration has been discovered."* ### Scripts Ordered shell scripts that bring your application to a healthy, running state. They run in the shell for your project's platform — bash on Linux, PowerShell on Windows — which is fixed when you choose the platform during Build Environment setup, not by whichever daemon happens to pick up the work. Write them for that shell. Common scripts include: | Script | Purpose | | - | - | | **install** | Install dependencies (e.g., `npm install`, `pip install -r requirements.txt`) | | **build** | Compile or bundle the application | | **seed\_db** | Apply database migrations and load any fixture or seed data the application needs to run | | **run** | Start the application process | | **healthcheck** | Verify the application is responding (e.g., `curl http://localhost:3000/health`) | | **smoke** | Exercise the running application enough to prove it actually works, not just that it started | | **test** | Run the project's test suite | Two of these are worth explaining, because they are the ones teams do not expect: **`seed_db`** runs after **build** and before **run**. Many applications start but do nothing useful against an empty database, so separating "prepare the data" from "start the app" means the Morph Platform can restart your application without re-seeding it every time. **`smoke`** is required for the origin application, and it is the check that makes validation meaningful. A health check tells you a process is listening; a smoke test tells you the application works. Until a smoke run passes, the Morph Platform does not treat your origin lifecycle as validated — even if every other script succeeded — because a migration validated against an application that was never really working proves nothing. > [!NOTE] > > If your lifecycle looks validated and then returns to **Draft**, a failing or missing smoke script is the usual reason. The status banner names what needs attention. ![Scripts section with the discovered lifecycle scripts](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/scripts-section.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=6c881babcb84e71427795d2300ca2658) Click a script name to expand it. The expanded view shows: * **Inline code editor** - Edit the script content directly. Scripts are executed as shell commands. * **Logs** - The stdout output from the last validation run, with the exit code and duration. * **Errors** - The stderr output. A bug icon appears on the script header if the last run failed with stderr output. ![Expanded script showing the inline editor, log viewer, and action buttons](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/script-expanded-logs.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=8d5fe6ef2e2b7b3de111f5cfc78a8004) Scripts run in order, and you can drag the handle on a script to reorder it. To add one, click **Add Script**, enter a name, and press Enter. To remove one, expand it and click **Delete**. ### Environment Variables Key-value pairs your application needs at build or runtime. Variables discovered from the codebase are pre-populated; you can add, edit, or remove them with **Add Variable**. Variables marked as **secrets** are encrypted at rest. Tick the **Secret** checkbox on a variable to mark it as a secret; once marked, the value is masked and a show/hide eye icon appears so you can reveal it when needed. ![Environment Variables section with a plain variable and a masked secret](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/env-vars-section.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=ea0f29664675094f1fc983bf0fadd921) ### Lifecycle Document A markdown overview describing how the application is structured, the execution order of scripts, and how each phase fits together. The agent generates it during Project Setup. It is **displayed read-only in the panel** — ask Knowledge chat to change it. A marker in the section header shows who wrote the configuration last: **Auto-discovered** when the agent did, **User-modified** once you save an edit of your own from the panel. ### Dockerfile and Dependencies These artifacts are **read-only in the panel** too — they carry the hint *"Read-only — ask the chat to update this."* To change the container image or the dependency manifest, ask Knowledge chat. ![Dockerfile section showing the read-only hint](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/chat-only-artifacts.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=b9fef140b10cc849add74caa608f509c) *** ## What You Edit Directly vs. What the Chat Owns Both routes are available, and they write to the same configuration. | Artifact | Edit in the panel | Ask the chat | | - | :-: | :-: | | Scripts | ✅ | ✅ | | Environment variables and secrets | ✅ | ✅ | | Lifecycle document | ❌ | ✅ | | Dockerfile | ❌ | ✅ | | Dependencies manifest | ❌ | ✅ | | Running validation | ❌ | ✅ | Only **Scripts** and **Environment Variables** are editable in place — everything else is displayed read-only and changed through the chat. Editing in the panel is best for a small, known correction: a wrong port, a typo in a command. Ask the chat when you want the agent to work out the change itself, touch several things at once, or investigate a failure. Typical chat asks: ``` The run script should bind to port 8080, not 3000. Re-validate after the change. ``` ``` Add a `migrate` script that runs `alembic upgrade head` before `run`. ``` ``` DATABASE_URL should point at a local Postgres on localhost:5432 for validation. Save it as a regular env var, not a secret. ``` *** ## Validation Status The status bar at the top of the Project Setup panel shows the current validation state: | Status | Meaning | | - | - | | **Validated** | All scripts ran successfully. The application started and passed the health check. | | **Draft — Needs Review** | The Morph Platform could not get the application running and healthy. Review the scripts, fix what's wrong, and re-validate. | | **Failed** | Validation ran but one or more scripts failed. The output is shown in the banner. | | **Imported — Needs Verification** | The setup came from [Organizational Knowledge](/customization/organizational-knowledge) at the organization level. Confirm it matches this project, then re-validate. | | **Pending** | Changes have been saved but not validated yet. | ![Status bar showing the Validated state with a last-validated timestamp](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/status-validated.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=688531054ab8d9d3aea289718753a41a) When the status is anything other than **Validated**, a banner explains what to do next and offers a **Re-validate** link. For **Draft** and **Failed**, the banner also includes the raw validation output. ![Draft — Review Required banner with validation output](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/status-draft.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=fa2efa2cb3bf9304b9a0c5098600b045) > [!NOTE] > > Saving any change to scripts or environment variables resets the status to **Pending** — the saved configuration hasn't been proven to work until you re-validate. Origin lifecycle status also gates the roadmap: the Morph Platform won't generate a roadmap while the origin lifecycle is **Draft**, **Failed**, or **Imported**. *** ## Editing and Re-validating After making changes in the panel: 1. Click **Save Changes** to persist your edits 2. Click **Re-validate** to run the full validation sequence again Both buttons sit in the drawer toolbar. **Re-validate** saves any unsaved changes first, then hands the run to Knowledge chat — the agent re-runs the lifecycle end to end, reports what it finds, and writes the result back. You can watch it happen in the chat panel. ![Re-validate and Save Changes buttons in the Project Knowledge toolbar](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/toolbar-buttons.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=0e540211bdecd55c2717b565af479ba2) > [!TIP] > > If you only need to fix a small script error, edit the script inline and click **Re-validate** - it handles saving for you. **Re-validate** is disabled while the chat is streaming, with the tooltip *"Wait for the chat to finish before re-validating."* Asking the chat directly works too: ``` Re-validate the origin lifecycle setup. ``` *** ## Authentication Handling When the Morph Platform sets up or validates your lifecycle, it probes API routes beyond the health endpoint to check whether the application has authentication that could affect automated testing. ### What Morph handles automatically The Morph Platform can detect and handle two types of authentication without manual intervention: * **Disable flags** — Many frameworks offer an environment variable or config setting that disables authentication in development or test mode (for example `DISABLE_AUTH=true`, `AUTH_ENABLED=false`, or framework-specific flags like `EnableTesting`). When the Morph Platform finds one, it registers the variable, restarts the application, and verifies that protected endpoints are now accessible. * **Static tokens** — If the application uses a fixed API key or Bearer token (e.g. an `X-API-Key` header), the Morph Platform asks you for the token with a **Provide Secret** card, stores it encrypted, and adds a verification script that confirms the token works. In both cases, the Morph Platform adds an **authcheck** lifecycle script that hits a protected endpoint with the configured auth method and fails if authentication is not working. This script runs alongside your other lifecycle scripts during every validation. ### What requires your attention * **Session-based login (username/password)** — Applications that require a `POST /login` call to obtain a session cookie or Bearer token. the Morph Platform reports this as detected but unsupported for automated bypass. * **OAuth / SSO / MFA** — External identity provider flows that involve browser redirects, third-party consent screens, or multi-factor challenges. These cannot be automated. When the Morph Platform detects these types, it documents the finding and shows an **"Unsupported Authentication Detected"** banner in the Project Setup panel. The banner explains that validation steps requiring authenticated access may be skipped, along with details about the specific auth type found. ![Unsupported Authentication Detected banner](https://mintcdn.com/modelcodeai/5Nid33zOcddhC__h/images/lifecycle-setup/auth-warning-banner.png?fit=max\&auto=format\&n=5Nid33zOcddhC__h\&q=85\&s=3012658bbb954bf9829fc975b857437a) > [!WARNING] > > **The Morph Platform cannot bypass login flows, external identity providers, or multi-factor challenges.** If your application relies on OAuth, SSO, MFA, or a `POST /login` session handshake, those auth-protected routes will be **unreachable during automated testing**. You have two options: > > 1. **Follow one of the [manual steps below](#manual-steps-for-unsupported-auth-types)** to configure authentication yourself (e.g. add a disable flag, seed a test user, add a login script, or use the connect strategy). > 2. **Accept reduced functional testing coverage.** The Morph Platform will still validate install, build, run, and health check — only runtime behavior verification of auth-gated endpoints is skipped. ### Manual steps for unsupported auth types If the Morph Platform can't figure out your application's auth automatically, you can prepare the environment yourself so that protected surfaces become reachable. Below are common patterns — pick the one that fits your stack. You can apply any of them by asking the chat, or by editing the panel directly. #### Add a test-mode environment variable Most frameworks have a way to relax or skip authentication in non-production environments. Add that variable to the **Environment Variables** section, for example: | Framework / Pattern | Variable | Value | | - | - | - | | Generic disable flag | `DISABLE_AUTH` | `true` | | Rails / Devise | `RAILS_ENV` | `test` | | Django | `DJANGO_SETTINGS_MODULE` | `myapp.settings.test` | | Spring Boot | `SPRING_PROFILES_ACTIVE` | `test` | | .NET | `ASPNETCORE_ENVIRONMENT` | `Development` | | Express / Passport | `AUTH_ENABLED` | `false` | Re-validate after the change so the Morph Platform confirms protected endpoints are now reachable. #### Seed a test user and add a login script If your application uses session or token-based authentication, the alternative is to give the Morph Platform a way in rather than switching authentication off. That takes two scripts: 1. **A `seed_db` script** that creates a test user, using whatever your project already uses for this — your ORM's console, a management command, a seed script, or a SQL fixture. 2. **An `authcheck` script**, ordered after `healthcheck`, that logs in as that user and confirms a protected endpoint responds. It should exit non-zero if that fails, so a broken login surfaces as a failed script rather than as confusing test results later. You do not have to write either from scratch. Describe your authentication setup in chat and ask the agent to add them — it can read how your application does authentication and propose scripts that fit, which is usually faster and more accurate than adapting a generic example. 3. **Store the test account's credentials as secrets** in the environment variables section so they are encrypted at rest. #### Use the connect strategy with a pre-authenticated instance When none of the above options work (e.g. OAuth with an external IdP that cannot be mocked), consider the **[connect strategy](/setup/lifecycle-strategy#you-run-your-app-connect)**. Run the application yourself with authentication already configured, and point the Morph Platform at the live, authenticated instance. The Morph Platform skips install/build/run and only needs a base URL and health check. *** ## Origin and Target The Morph Platform maintains separate lifecycle configurations for each side of the migration. | | Origin | Target | | - | - | - | | What it describes | How the source application builds and runs | How the modernized application builds and runs | | When it's set up | Project Setup, with you in chat | Automatically, during the foundation milestone (Milestone 1) | | What it's used for | The behavioral baseline for functional testing | Verifying that migrated code actually builds, runs, and passes its health check | Target discovery reuses the origin configuration as a starting point, so a clean, accurate origin setup directly improves the target result. Both sides stay editable in the panel and through chat for the rest of the project. *** ## Tips * **Check the Errors tab first.** When a script fails, the stderr output usually points directly at the problem - a missing dependency, a wrong port, or a typo in the command. * **Keep scripts minimal.** Each script runs in a fresh shell process. If two commands need to share shell context — activating a virtual environment before running a command, say — chain them in a single script: with `&&` on Linux and macOS, and with `;` or separate lines on Windows. * **You don't need to change directory.** The Morph Platform keeps the working directory consistent across every command in a job. Only `cd` when a command has to run in a nested folder. * **Set environment variables in the UI, not in your scripts.** Variables added to the **Environment Variables** section are available to every script and can be encrypted if sensitive. A variable exported inside one script does not survive into the next. * **Private dependencies need credentials on the machine.** Scripts run exactly as written. If your package manager needs to authenticate to a private repository, those credentials have to be present on the host already, or supplied as an encrypted environment variable. * **Use environment variables for configuration.** Avoid hardcoding ports, database URLs, or API keys in scripts. Set them as environment variables so they are easy to change and can be encrypted if sensitive. * **Answer the agent's questions rather than skipping them.** A skipped question means the agent guesses, and a wrong guess usually surfaces later as a validation failure. * **Reuse a working setup.** Once the lifecycle validates, it becomes available as [Organizational Knowledge](/customization/organizational-knowledge) so the next project on the same repositories can import it and skip Project Setup. *** ## Related Docs > **[Project Knowledge](/customization/project-knowledge)** > > The drawer that hosts Project Setup, Knowledge chat, and the rest of your project context > **[Lifecycle Strategy](/setup/lifecycle-strategy)** > > Choose whether the agent builds and runs your app, or connects to a running one > **[Validation Level](/setup/validation-level)** > > Why Project Setup only runs at the High validation level > **[Acceptance Criteria](/setup/acceptance-criteria)** > > Quality gates built on top of your lifecycle scripts > **[Self Hosted](/setup/build-environment/self-hosted-daemon)** > > Run ModelDaemon on your own infrastructure for projects with private dependencies > **[Validation Hub](/migration/validation-hub)** > > Where lifecycle script results are reported during milestone execution This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.