> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to declarative configuration

> Move from classic environment setup to declarative blueprints. Devin can handle most of the migration for you.

Declarative configuration (blueprints) is the next generation of environment setup: version-controlled, composable, and auto-updating. This guide walks you through migrating from the classic interactive wizard.

<Warning>
  Classic environment setup is being deprecated. There are two dates to be aware of:

  * **June 30, 2026:** All organizations move to declarative configuration (blueprints). Your classic configuration isn't deleted, and you can revert back to it.
  * **July 31, 2026:** Your classic machine configuration stays available as a reference until this date, so you can refer or revert to it while finishing your migration. After July 31 it's removed.

  Migrate before June 30, 2026 to avoid interruptions. Enterprise customers who need more time should contact their account team.
</Warning>

## Why migrate?

With the classic setup wizard, Devin's environment is a manually configured snapshot that can drift over time. Dependencies go stale, configuration changes require re-running the wizard, and there's no version history. Declarative configuration solves this:

* **Automatic updates**: blueprints rebuild when your repo changes, so dependencies stay current
* **Version controlled**: your environment configuration lives alongside your code, with full history
* **Composable**: enterprise, org, and repo blueprints layer together cleanly
* **Reproducible**: every build produces the same result from the same blueprint
* **Faster sessions**: snapshots are pre-built with repos cloned and dependencies installed, so sessions start ready to work

<Info>
  Your classic setup keeps working until June 30, 2026, then stays available for migration until July 31, 2026, and you can revert your organization back to it before then.
</Info>

## Before you start

<AccordionGroup>
  <Accordion title="Check that your org is eligible">
    Look for a banner on the **Machine Configuration** page (the classic setup page) that says **"Switch to declarative environment configuration"**. If you see it, your organization is eligible.

    If you don't see the banner, declarative configuration hasn't been enabled for your organization yet. It's being rolled out gradually. Contact your enterprise admin or reach out to support.
  </Accordion>

  <Accordion title="Who can migrate">
    Migration requires **org admin** permissions (`ManageOrgSettings`). If you're not an org admin, you'll see an "Admin access required" message on the migration page.
  </Accordion>

  <Accordion title="Is this reversible?">
    Yes, until July 31, 2026. Your existing snapshot is preserved, so you can revert before then to switch your organization back to it. After June 30, all organizations are on declarative configuration, though your classic machine configuration stays available to revert to until July 31, 2026.
  </Accordion>
</AccordionGroup>

## Migration steps

### 1. Go to the migration page

Navigate to **Settings > Environment migration**, or click **Get started** on the banner shown on the Machine Configuration page.

### 2. Enable declarative configuration

Click **Enable for organization**. This switches your org to use blueprint-based snapshots for new sessions.

<Info>
  This doesn't affect your existing snapshot. It's preserved in case you need to revert.
</Info>

### 3. Let Devin generate your blueprints

**Devin does the work for you.**

Click **Start migration** and select the repositories you want to migrate first. You don't have to migrate everything at once. Start with your most-used repos.

When you start the migration, Devin creates **two sessions**:

* A **main session** running on the new declarative environment, which writes the blueprints
* A **helper session** running on your existing snapshot, which Devin uses to inspect what's currently installed (language versions, system packages, running services, etc.)

Devin examines your existing snapshot, figures out what tools and dependencies are installed, and generates the equivalent blueprint configuration. The results appear on your **Settings > Environment > Blueprints** page.

<Tip>
  Your existing snapshot is a "black box" of everything you've configured over time. Devin inspects that snapshot, catalogs what's installed, and writes it down as a reproducible blueprint automatically.
</Tip>

### 4. Review and adjust

After Devin generates the blueprints:

1. Go to **Settings > Environment > Blueprints** to review what was generated
2. Check the build status. Look for **Success**.
3. Start a test session to verify everything works:
   * Confirm repos are cloned and dependencies are installed
   * Try running your lint, test, and build commands
   * Verify any custom tools or runtimes are available

If something is missing, edit the blueprint directly. You can add `initialize` steps, `maintenance` commands, or `knowledge` entries.

## Rolling back

If something isn't working, you can revert before July 31, 2026:

1. Go to **Settings > Environment migration**
2. Click **Revert to classic**
3. Your organization immediately switches back to using the previous snapshot

Your existing snapshot is fully preserved. Nothing is lost. You can attempt the migration again whenever you're ready.

<Info>
  After June 30, 2026, all organizations run on declarative configuration, but your classic machine configuration stays available to revert to until July 31, 2026, when it's removed. Enterprise customers who need more time should contact their account team.
</Info>

## Mapping classic setup steps to blueprints

If you prefer to write your blueprint manually (or want to understand the mapping), here's how the classic wizard steps translate:

| Classic setup step    | Blueprint equivalent             | Notes                                                                                          |
| --------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------- |
| Git pull              | *Automatic*                      | Blueprints handle git clone and pull automatically                                             |
| Secrets               | Secrets tab in blueprint editor  | Configure in the **Secrets** tab within each blueprint editor                                  |
| Install dependencies  | `initialize`                     | One-time setup: language runtimes, system packages, global tools                               |
| Maintain dependencies | `maintenance`                    | Dependency commands surfaced to the agent at session start: `npm install`, `pip install`, etc. |
| Lint                  | `knowledge` (`name: lint`)       | Reference only, not executed during builds                                                     |
| Test                  | `knowledge` (`name: test`)       | Reference only, not executed during builds                                                     |
| Run app               | `knowledge` (`name: dev-server`) | Reference only, not executed during builds                                                     |
| Additional notes      | `knowledge`                      | Free-form entries for Devin                                                                    |

### Example

**Classic setup:**

* Install dependencies: `nvm use 20 && npm install`
* Maintain dependencies: `npm install`
* Lint: `npm run lint`
* Test: `npm test`
* Run app: `npm run dev`

**Equivalent blueprint:**

```yaml theme={null}
initialize: |
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  source ~/.bashrc
  nvm install 20

maintenance: |
  npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
  - name: dev-server
    contents: npm run dev
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Build failed">
    Check the build logs for the specific error. Common causes:

    * A command that worked in the classic setup terminal doesn't work in the build context (e.g., interactive prompts that need `-y` flags)
    * Missing secrets (make sure secrets are configured in the **Secrets** tab within the blueprint editor)
    * Compare your blueprint commands against your original commands to spot differences
  </Accordion>

  <Accordion title="Dependencies missing in sessions">
    Make sure your `maintenance` section includes the same dependency install commands as the classic **Maintain Dependencies** step. Commands like `npm install` or `pip install -r requirements.txt` belong in `maintenance`, not `initialize`.
  </Accordion>

  <Accordion title="Devin doesn't know how to lint or test">
    Check that your `knowledge` section has items named `lint` and `test` with the correct commands. Devin looks for these names when verifying its work.
  </Accordion>

  <Accordion title="Custom shell profile changes aren't applied">
    If your classic setup modified `~/.bashrc`, `~/.profile`, or other shell config, move those into `initialize`:

    ```yaml theme={null}
    initialize: |
      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
      echo 'export NODE_ENV=development' >> ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Git pull isn't working">
    Blueprints handle git clone automatically during builds. If repos aren't being cloned, check that they're added on the **Settings > Environment > Blueprints** page and that Devin has access through your Git integration.
  </Accordion>
</AccordionGroup>

## Related pages

* [Declarative environment configuration](/onboard-devin/environment/blueprints)
* [Blueprint reference](/onboard-devin/environment/blueprint-reference)
* [Template library](/onboard-devin/environment/templates)