Repo Connect currently supports Typescript and Python. We are working on adding support for other languages and configuration for Docker in Docker. If you have suggestions or are interested in a specific language, please contact us at support@runloop.ai.

​
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

​
Containerized services within a Repo Connect

Repositories often have dependencies on containerized services that run alongside your agent, codebase, or devbox. Our repository connection process surfaces any service declared in the repository’s Github Actions workflow files as a part of the final blueprint. You can confirm this by querying the blueprint and before launching a devbox with the available services initialized. You will need:
  • blueprint_id from a Repo Connect Inspection to confirm the available services
  • blueprint_id or repo_connection_id to launch a devbox with the services
The following example shows how to launch a devbox from Repo Connection rpc_123456789 that’s created blueprint with id bpt_123456789 with the postgres service available. The required_services when launching a devbox will be used to determine which services to start and each service must match one of the name elements in the containerized_services list otherwise the devbox will fail to start. 
  "containerized_services": [
    {
      "name": "postgres",
    },
    ...
  ]

curl --request GET \
  --url https://api.runloop.ai/v1/blueprints/bpt_123456789 \
  --header 'Authorization: Bearer <token>'

curl --request POST \
  --url https://api.runloop.ai/v1/devboxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "devbox-name",
    "repo_connection_id": "rpc_123456789",
    "launch_parameters": {
      "required_services": ["postgres"]
    }
  }'

​
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
Repo Connect works best with repositories that follow standard project conventions and include clear build instructions. For complex or non-standard setups, review the partial analysis results and add any missing configuration details.