Repo Connect - Build and Run code end-to-end on Runloop

​

Overview

Repo Connect revolutionizes how AI agents interact with your codebase by automatically analyzing and understanding your repository’s structure, dependencies, and build processes. This enables your AI agent to work with existing projects just like a human developer would - with the ability to build, test, and run your code without manual prompting.

​

About Repo Connect

Repo Connect uses a GitHub token to securely access your repository and employs a combination of semantic analysis and AI agents to intelligently discover:

• Setup and build commands
• Test execution procedures
• Package managers and dependency installation
• Environment initialization requirements
• Available project commands and scripts

When successful, Repo Connect generates a Runloop blueprint that can then be used to create new Devboxes that are immediately ready for your AI agent to operate on your code, enabling features like running specific code paths, tracing and debugging, and making informed changes.

​

Creating a Repo Connect Analysis

​

Basic Repository Analysis

curl --request POST \
  --url https://api.runloop.ai/v1/repositories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "simple-todo",
  "owner": "runloopai"
}'

This initiates analysis of your repository, automatically discovering build tools, dependencies, and setup requirements.

​

Understanding Analysis Results

When Repo Connect completes its analysis, you’ll receive detailed information about your repository’s structure and requirements:

​

Successful Analysis

A successful analysis provides:

• Extracted Tools: Discovered commands for building, testing, and running your project
• Package Manager: Identified dependency management system (npm, pip, maven, etc.)
• Setup Commands: Environment initialization and workspace preparation steps
• Blueprint: A reusable configuration for future Devbox instances

​

Partial Analysis

If Repo Connect cannot fully analyze your repository, it generates a partial inspection with discovered information pre-filled. You can then edit and complete the missing details to achieve a working state for your AI agent.

The analysis results follow this structure:

interface RepositoryVersionDetails {
  analyzed_at: number;
  commit_sha: string;
  extracted_tools: {
    commands: Record<string, string>;
    package_manager: string;
  };
  repository_setup_details: {
    blueprint_id: string;
    env_initialization_command: string;
    workspace_setup: Array<string>;
  };
  status: 'inspecting' | 'inspection_failed' | 'success';
}

​

Using Analyzed Repositories

Once Repo Connect has analyzed your repository, you can create Devboxes that are immediately ready for AI agent interaction:

import os
from runloop_api_client import Runloop

client = Runloop(
    bearer_token=os.environ.get("RUNLOOP_API_KEY"),  # This is the default and can be omitted
)

list_inspections = runloop_client.repositories.list_inspections(id='')
inspection = next((inspection for inspection in list_inspections.inspections if inspection.status == "image_build_success"), None)
if inspection:
    dbx = await runloop_client.devboxes.create_and_await_running(
        name='devbox-name',
        blueprint_id=inspection.blueprint_id
    )
    print(dbx.id)

Your AI agent can now:

• Execute discovered build and test commands
• Navigate and understand your codebase structure
• Make informed changes based on project conventions
• Debug and trace execution paths
• Install and manage dependencies automatically

​

Refreshing Repo Connect

As your repository evolves, you can refresh the Repo Connect analysis to capture new changes, dependencies, or build processes:

curl --request POST \
  --url https://api.runloop.ai/v1/repositories/${REPO_CONNECT_ID}/refresh \
  --header 'Authorization: Bearer <token>'

This allows you to see the progression of your development environment and ensure your AI agent always has the most current understanding of your project.

​

Best Practices

​

Repository Preparation

1. Clear Documentation: Well-documented README.md or AGENTS.md files help Repo Connect understand your project structure
2. Standard Build Files: Use conventional build files (package.json, requirements.txt, Makefile) when possible
3. Environment Files: Include .env.example or similar files to help identify required environment variables. Repo Connect will ask for secret values if required

​

Token Security

1. Use GitHub tokens with appropriate repository access permissions
2. Regularly rotate your tokens and update Repo Connect configurations
3. Monitor token usage and revoke access if needed

​

Blueprint Management

1. Review generated blueprints to ensure they capture your project’s requirements accurately
2. Version your blueprints alongside your code to maintain consistency
3. Test blueprints with fresh Devbox instances to verify completeness