Quick-lookup reference for environment.yaml syntax and behavior. For concepts and guides, see Environment Configuration.
Field reference
Top-level fields
| Field | Type | Required | Executed during | Description |
|---|
initialize | string or list | No | Build only | One-time setup commands. Results are saved in the machine image. Should be idempotent. |
maintenance | string or list | No | Build + session start | Recurring dependency commands. Keep fast and incremental. |
knowledge | list of objects | No | Never (reference only) | Information loaded into Devin’s context at session start. |
| Field | Type | Required | Description |
|---|
name | string | No | Human-readable label shown in build logs. Makes failures easier to identify. |
run | string | No | Shell command(s) to execute. Multi-line strings are supported. Steps without run are skipped. |
Knowledge entry fields
| Field | Type | Required | Description |
|---|
name | string | Yes | Identifier (e.g., test, lint, startup, architecture, notes). |
contents | string | Yes | The reference content. Not executed as commands. |
Execution details
- Commands run in bash with
set -e enabled — if any line fails, the step stops immediately.
- Repo-specific commands run from the repo root (
~/repos/<repo-name>). Enterprise and org-wide commands run from the home directory (~).
- Each step in the expanded form runs in its own shell context.
| Scope | Timeout |
|---|
| Individual command | 1 hour |
| Total build | 2 hours |
- Use subshells for subdirectory commands:
(cd packages/frontend && npm install).
- Prefer incremental installs in
maintenance (e.g., npm install instead of npm ci).
- Avoid build commands (
npm run build, make) in maintenance — they run every session.
- Add
-y flags to prevent interactive prompts: sudo DEBIAN_FRONTEND=noninteractive apt-get install -y.
- Commands should be safe to run multiple times —
maintenance runs every session.
Devin’s base image (Ubuntu 22.04, x86_64) includes these tools. You don’t need to install them.
| Category | Included |
|---|
| Languages | Node.js (via nvm), Python 3.12 (via pyenv, with 3.9–3.11 also available), Rust (via rustup), Java (OpenJDK 17), Scala, Go |
| Package managers | npm, yarn, pnpm, pip, cargo |
| Version control | git, gh (GitHub CLI), git-lfs |
| Containers | Docker (with Compose plugin — use docker compose, not docker-compose) |
| Build tools | make, build-essential (gcc, g++) |
| Utilities | curl, wget, jq, ripgrep, direnv, awscli, ffmpeg, Homebrew, OpenVPN |
| Browsers | Chrome (for browser-based testing) |
This list may not be exhaustive. Run which <tool> or <tool> --version in a Devin session to check. If something is missing, install it in your initialize section.
Glossary
| Term | Definition |
|---|
| Configuration | A saved environment setup (the YAML content). Each repo/org/enterprise has its own. |
| Configuration version | A specific revision of a configuration. Each save creates a new version. |
| Build | The process of executing your configuration to create a machine image. |
| Machine image | The saved environment created by a successful build. Sessions boot from the latest successful image. |
| Configured | A repository with explicit YAML configuration (initialize/maintenance/knowledge). |
| Included | A repository cloned into the machine image but with no custom configuration. |
| Available | A repository accessible to the org but not added to the environment. |
| $ENVRC | A special file for setting environment variables. Similar to GitHub Actions’ $GITHUB_ENV. |
| Partial success | A build where the core succeeded but some repository-level setups failed. |
Next steps
