Devin operates by loading a snapshot of a virtual machine at the start of each session. For Devin to be most effective, this snapshot should include all the repositories you want Devin to work on, as well as any tools or dependencies Devin might need to work on your codebase. This way, Devin can focus on writing code instead of having to set up its environment every time!

In this guide, we’ll go over how to onboard Devin onto one of your repositories and configure Devin’s workspace (the virtual machine snapshot). You can think of this as setting up Devin’s machine for his first day of work.

Setting up Devin’s workspace correctly will significantly improve Devin’s performance on your codebase. Imagine if every time you started a task, your laptop and part of your memory were wiped—that’s what happens to Devin with an incorrect or incomplete setup!

​
Set up a repository

First, make sure Devin has access to your repositories. Repositories can be added at any point by going to Settings > Integrations and configuring Devin’s access.

Refer to the GitHub Integration Guide for more information

Now, go to Settings > Devin’s Workspace and click on a repository you want Devin to work on. You should see the following screen.

You can now use the embedded VS Code on the right side to edit Devin’s virtual machine. Each repository will be in its own directory under ~/repos. Do not move or delete those directories. The repository you’re currently setting up has already been cloned, and the machine also contains any other repositories you’ve set up in the past.

After you finish the repository set up, a snapshot of the virtual machine will be saved. Future Devin sessions will start from this snapshot and will include any tools or dependencies you’ve installed during the setup process.

Follow the below steps and the instructions on screen to set up the repository. You can always come back and edit the repository setup after saving. You can also follow along our video guide below.

1

Git Pull

Enter the command Devin should run at the start of each session to pull the latest changes from the repository. In most cases, you should keep the default command. Make sure that Devin has access to the submodules in the repository.

2

Install Dependencies

Use VS Code to set up all the tools and dependencies Devin will need to work on the repository. After this step, Devin should be able to run all the commands he needs (e.g. lint, test, build, etc.) without any additional installation steps. Devin’s machine is running on Ubuntu 22.04 (x86_64).

Try pressing Ctrl+K or Cmd+K (Mac) in the terminal to automatically generate an installation command.

Suggestions:

  • Install compilers, interpreters, build tools, package managers, linters, formatters, test runners, etc.
  • Install package dependencies (e.g. npm install, pip install -r requirements.txt, etc.)

Keep in mind that the changes you make will be applied when Devin is working on other repositories as well. Be careful about global package installations and consider using a virtual environment if possible.

Devin will run his commands in a bash shell. To test out your setup, you can create a fresh new terminal in VS Code.

For more advanced setup, such as configuring custom interpreter versions for each repo or setting up environment variables, check out the examples section.

3

Maintain Dependencies

Enter the command Devin should run at the start of each session to keep dependencies up to date. This likely should be the same command as the one you used to manually install dependencies (e.g. npm install, pip install -r requirements.txt, etc.).

The purpose of this is to ensure that Devin can update his local dependencies if they get added to the git repository.

4

Setup Lint

Enter commands that Devin should run to lint the repository. Devin will look at the output of these commands before he commits changes.

These commands should terminate in 5 minutes or less so Devin doesn’t have to wait too long for them. Click verify to check that the commands are working.

Tips:

  • If necessary, you can first run the commands in the VS Code terminal to induce caching.
  • If the command needs to run in a specific directory, you can use cd like so: cd <directory> && <lint command>.
  • If your project doesn’t have a lint command, you can include your build command so Devin checks for compilation errors.
  • You can also include a command here that checks for code formatting style.
  • If the lint procedure for your process is complex, you can skip this step and explain linting to Devin in the Additional Notes step below.
    Check out the troubleshooting section if you encounter issues with verifying your commands.
5

Setup Tests

Enter commands that Devin should run to test the repository. Like with the lint commands, Devin will look at the output of these commands before he commits changes. These commands also have a 5 minute time limit. Click verify to check that the commands are working.

Tips:

  • If necessary, you can first run the commands in the VS Code terminal to induce caching.
  • If the command needs to run in a specific directory, you can use cd like so: cd <directory> && <test command>.
  • If the test procedure for your process is complex, you can skip this step and explain testing to Devin in the Additional Notes step below.
    Check out the troubleshooting section if you encounter issues with verifying your commands.
6

Configure Secrets

Set up any secrets Devin will need. When possible, we recommend directly adding a .env file to Devin’s workspace. This example shows how to do this with direnv.

Other secrets, such as passwords, can be added in the secrets dashboard.

7

Setup Local App

Let Devin know how to run your code locally. This is useful if Devin needs to run your code to test or debug changes.

Test the commands yourself in the VS Code terminal to ensure Devin is actually able to run them.

8

Additional Notes

Add any additional notes that you think are important for Devin to know when working on this repository.

We recommend automating as much of the setup process as possible. Check out the examples section for some examples of how to do this. This will make it faster for Devin to get started working on your codebase right away in future sessions.

Once you’ve completed all the steps, click finish. We’ll verify that all the commands are working and then save the snapshot. This might take a few minutes. Once the snapshot is saved, future Devin sessions will be able to use the setup you’ve configured.

We recommend setting up a gitignore file for the repository if you don’t have one. This will help prevent Devin from making mistakes when committing files, and it will also make it easier for you to view Devin’s changes when you work with him in the IDE.

​
Examples

Below are some examples of how to set up Devin’s workspace for different use cases.

Since Devin runs all commands using bash, one common pattern is to edit the ~/.bashrc file to automatically set up Devin’s shell for him. You can run devin ~/.bashrc in the terminal to edit the file in VS Code.

​
Configuring Separate Node Versions for Different Repositories

Say you have two repositories that require different versions of Node, and you want Devin to automatically use the right version for each repository. We’ll use nvm to install and manage the Node versions. nvm should already be installed in Devin’s machine.

First, we’ll install the two versions of Node by running the following commands in the VS Code terminal:

nvm install 18
nvm install 20

Next, open up ~/.bashrc by running devin ~/.bashrc in the terminal. Append the following to ~/.bashrc.

function cd1() {
  builtin cd "$@"

  if [[ "$PWD" == "$HOME/repos/node18"* ]]; then
    nvm use 18 >/dev/null 2>&1
  elif [[ "$PWD" == "$HOME/repos/node20"* ]]; then
    nvm use 20 >/dev/null 2>&1
  fi
}

alias cd='cd1'
cd $PWD

This will run nvm use 18 whenever Devin is in the node18 repo and nvm use 20 whenever Devin is in the node20 repo.

​
Configuring Environment Variables

We’ll go over how to use direnv to manage environment variables. First, we’ll follow direnv’s installation instructions to install it on Devin’s machine.

We’ll first install direnv by running the following command in the VS Code terminal:

sudo apt install direnv

Then, we’ll append the following to ~/.bashrc to set up the direnv hook. You can open up ~/.bashrc by running devin ~/.bashrc in the terminal.

eval "$(direnv hook bash)"

Now, we can create a .envrc file in the root of our repository that might look something like this.

export ENV_VAR=1
export ANOTHER_ENV_VAR=2

Finally, we’ll run direnv allow in the terminal to load the environment variables.

Devin will now have the environment variables in our .envrc file added to his environment when working in our repository in future sessions.

We recommend adding .envrc to your .gitignore file so that Devin doesn’t accidentally commit it to the repository.

​
Adding Directories to the System PATH

We can edit ~/.bashrc to add directories to the system PATH. This will make it easier for Devin to run the executables in those directories. For example, we can append the following to ~/.bashrc which will add the ~/bin directory to the system PATH.

export PATH="$HOME/bin:$PATH"

Now, Devin will be able to run the executables in the ~/bin directory without having to specify the full path.

​
Logging In to Websites

During repository setup, you can use the Browser tab to log in to any website that you want Devin to interact with. These session cookies will be stored in Devin’s workspace and will be available to Devin in future sessions. If you are using a website that times out your login frequently, you will also want to set Devin up with credentials in your Secrets dashboard.

​
Troubleshooting

​
Why aren’t my commands being verified?

If you run into an error when verifying one of the commands, try to inspect its output in the VS Code terminal and also try to run the command yourself in a fresh terminal.

  1. Check the path of the executable you are running. We strongly recommend either using absolute paths or adding executables to the system PATH.
  2. Make sure you’ve installed the necessary tools and dependencies to run the command. If you haven’t, use the terminal to install them and verify again.
  3. Check that the commands are being run in the right directory. If the commands need to run in a specific directory, you can use cd like so: cd <directory> && <command>.
  4. Check that you are using the right language versions (e.g. right versions of Node, Python, etc.). Check out this section for an example of how to configure separate language versions for different repositories.
  5. Check that you’ve setup your bashrc so that a fresh bash shell has access to the necessary tools. Try running your commands in a fresh terminal. If they don’t work, you will likely need to edit your bashrc, for example by running certain setup commands or editing the system PATH. Consult the documentation for the tools you’re using on what you need to do.

Commands will timeout after 5 minutes. You can induce caching by running the commands in the VS Code terminal before verifying. We do not recommend giving Devin commands that take longer than 5 minutes to run, as it will significantly slow him down.

​
Homebrew is asking me for a password

This is a bug in Linux Homebrew. Run CI=1 brew install <package> instead.

​
Devin can’t run my lint/test commands in sessions

Take a look at the output of Devin’s terminal to see if you can spot any errors. You can also try running the commands yourself in a fresh terminal to see if they work. If needed, you can revisit the repository setup process to make changes to Devin’s workspace.

​
The git pull step isn’t working

Double check that Devin has access to the repository and submodules of the repository. Also check out the GitHub Integration Documentation if you run into any permission issues.

​
Need to edit?

You can always edit or add a new repo in Settings > Devin’s Workspace.

To edit an existing repo, click on it in Devin’s Workspace > click “edit” > click “Set up in VSCode”.

It is also possible to completely reset Devin’s machine state by going to your Settings > Devin’s Workspace tab, opening the Danger Zone dropdown, and using the ‘Reset machine setup’ option. Note that this will remove all repositories you have set up.

​
All Done!

Congrats! You’ve onboarded Devin and can start building together. It’s time to start your first session. Keep in mind that Devin works best when you:

  • Tell Devin how to check its progress
  • Break down big tasks
  • Share detailed requirements upfront
  • Run multiple sessions in parallel

If you need support please don’t hesitate to drop us an email at support@cognition.ai.