Mount a Code Repository on a Devbox

Enable AI agents to work with full projects: access public and private repositories

Start with the Runloop Quickstart to use the examples below.

Overview

Enabling your AI agent to work on full existing code projects unlocks a new set of capabilities. This guide explains how to give your AI agent access to entire codebases, allowing it to make changes and run projects end-to-end like a human engineer.

Using Code Mounts

While you can use normal shell exec commands to clone a public GitHub repository, Runloop’s Code Mounts provide a more powerful way to manage source code on your Devboxes. Code Mounts allow you to mount a repository into your Devbox under your user’s home directory.

Creating a Devbox With a Public Code Mount

To add a CodeMount to your Devbox, specify the GitHub repo owner owner and name when you create it:

Python

devbox = await runloop.devbox.create(
    code_mounts=[
        {
          "repo_name": "rl-cli",
          "repo_owner": "runloopai",
        }
    ]
)
print(f"Devbox created with ID: {devbox.id}")

# ~/rl-cli is mounted
exec_result = await devbox.cmd.exec("ls")
print(await exec_result.stdout())

This will clone the repo onto the Devbox and allow you to pull changes and branches.

If you want to create pull requests or make other changes to the remote repo you must configure your Git Auth as described below.

Connecting to Private GitHub Repositories

To enable your Devbox to interact with private GitHub repositories, you need to provide proper authentication credentials. Runloop offers several methods to achieve this.

Using Code Mounts with GitHub Token

When you create a Devbox with a Code Mount, Runloop automatically sets up the GH_TOKEN environment variable and credential cache for you. This authenticates all command-line tools in your Devbox with your GitHub token. This allows your AI agent to use Github and open authenticated pull requests using the gh cli tool.

Python

devbox = await runloop.devbox.create(
  code_mounts=[
    {
      "repo_name": "acme-website",
      "repo_owner": "company",
      "token": os.environ.get("GH_TOKEN"),
    }
  ]
)

Manually Configuring Your Devbox for GitHub

Alternatively, you can configure your Devbox manually using setup_commands when you create your Devbox:

Python

devbox = await runloop.devbox.create(
  environment_variables={"GH_TOKEN": "<YOUR_GITHUB_TOKEN>"},
  setup_commands=[
    "git config --global credential.helper 'cache --timeout=3600'",
    "echo \"protocol=https\nhost=github.com\nusername=$GH_TOKEN\npassword=$GH_TOKEN\" | git credential-cache store"
  ]
)

# git clone now works
await devbox.cmd.exec("git clone https://github.com/company/acme-website.git")

This command:

1. Creates a new Devbox
2. Sets the GH_TOKEN environment variable with your GitHub token
3. Configures Git to use the credential cache
4. Stores your GitHub token in the Git credential cache for one hour

Note that the GH_TOKEN environment variable is only set while the setup commands are running; it is not saved directly to the Devbox. Using the credential cache with a timeout allows you to save limited use credentials to the Devbox image.

Adjust the --timeout value in the git config command to change how long the credentials are cached.

Best Practices for Token Security

1. Use tokens with the minimum required permissions for your tasks.
2. Regularly rotate your GitHub tokens.
3. Never commit or push files containing your tokens to version control.
4. Use environment variables when possible to avoid exposing tokens in command-line arguments.

By following these guidelines, you can securely enable your AI agent to work with full projects and private repositories, expanding its capabilities within the Runloop Devbox environment.