Skip to main content
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.

​
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
We recommend migrating to declarative configuration when you’re ready. Your classic setup continues to work in the meantime.

​
Before you start

Look for a banner on the Machine Configuration page (the classic setup page) that says “Switch to Devin’s new v2 environment”. 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.
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.
Yes. Your existing snapshot is fully preserved. You can revert at any time and your organization immediately switches back to the previous snapshot. Nothing is lost.

​
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.
This doesn’t affect your existing snapshot. It’s preserved in case you need to revert.

​
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 Environment configuration page.
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.

​
4. Review and adjust

After Devin generates the blueprints:
  1. Go to Settings > Environment configuration 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, revert at any time:
  1. Go to Settings > Environment migration
  2. Click Revert to classic setup
  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.

​
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 stepBlueprint equivalentNotes
Git pullAutomaticBlueprints handle git clone and pull automatically
SecretsSecrets panel in UIConfigure in Settings > Environment configuration
Install dependenciesinitializeOne-time setup: language runtimes, system packages, global tools
Maintain dependenciesmaintenanceRecurring per-session setup: npm install, pip install, etc.
Lintknowledge (name: lint)Reference only, not executed during builds
Testknowledge (name: test)Reference only, not executed during builds
Run appknowledge (name: dev-server)Reference only, not executed during builds
Additional notesknowledgeFree-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: 
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

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 blueprint editor’s secrets panel)
  • Compare your blueprint commands against your original commands to spot differences
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.
Check that your knowledge section has items named lint and test with the correct commands. Devin looks for these names when verifying its work.
If your classic setup modified ~/.bashrc, ~/.profile, or other shell config, move those into initialize:
initialize: |
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
  echo 'export NODE_ENV=development' >> ~/.bashrc
Blueprints handle git clone automatically during builds. If repos aren’t being cloned, check that they’re added to the Environment configuration page and that Devin has access through your Git integration.