Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt

Use this file to discover all available pages before exploring further.

Start with the Runloop Quickstart to use the examples below.

​
Overview

Agent Mounts allow you to attach pre-configured AI agents to your Devbox at creation time. Agents are reusable templates that define how to set up and run AI coding assistants or other automated tools on your Devbox.

​
Agent Source Types

Runloop supports several types of agent sources:
Source TypeDescriptionExample
GitClone an agent from a Git repositoryOpen source agents, custom agents
NPMInstall an agent from npm registryNode.js-based agents
PIPInstall an agent from PyPIPython-based agents
ObjectUnpack an agent from a storage objectPre-packaged agent bundles

​
Creating an Agent Mount

Use the mounts parameter with type: "agent_mount" to attach an agent to your Devbox: 
devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "agent_mount",
      "agent_name": "my-coding-agent",
      "agent_path": "/home/user/agent"
    }
  ]
)

​
Agent Mount Parameters

ParameterRequiredDescription
typeYesMust be "agent_mount"
agent_idNo*The ID of the agent to mount
agent_nameNo*The name of the agent to mount (uses most recent version)
agent_pathDependsPath where the agent should be mounted. Required for Git and Object agents. Ignored for npm and pip agents.
auth_tokenNoAuthentication token for private Git repositories
agent_setup_commandsNoAdditional setup commands to run after the agent is installed. These run in addition to any setup commands defined on the agent itself.
agent_launch_argsNoArguments to pass when launching the agent
Either agent_id or agent_name must be provided, but not both. Using agent_name will mount the most recent agent with that name.

​
Public Agents

Runloop provides pre-configured public agents that you can mount without creating your own. Public agents are automatically updated to the latest upstream version at least weekly. If you need a specific version, you can pin it by using agent_id instead of agent_name.
AgentDescription
claude-codeAnthropic’s Claude Code
codexOpenAI’s Codex
opencodeOpen-source coding agent
gemini-cliGoogle’s Gemini CLI
deepagentsDeepAgents CLI
Each agent requires API keys to authenticate with its underlying LLM provider. Use Agent Gateways to securely provide these keys without exposing them inside the devbox.
DeepAgents requires sqlite3 to be installed. This is handled automatically on the default devbox and Debian-based blueprints. If you use a custom blueprint, ensure libsqlite3-0 (or equivalent) is installed in your blueprint.
Mount a public agent by name just like any other agent: 
devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "agent_mount",
      "agent_name": "claude-code"
    }
  ]
)
You can also list available public agents using the API: 
public_agents = await runloop.agent.list_public()
for agent in public_agents.agents:
    print(f"{agent.name} v{agent.version}")

​
Examples

​
Mounting an Agent by Name

When you specify agent_name, Runloop will find the most recent agent with that name: 
devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "agent_mount",
      "agent_name": "code-reviewer",
      "agent_path": "/home/user/code-reviewer"
    }
  ]
)

# The agent is now available at /home/user/code-reviewer
result = await devbox.cmd.exec("ls /home/user/code-reviewer")
print(await result.stdout())

​
Mounting an Agent by ID

For precise version control, use the agent’s ID: 
devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "agent_mount",
      "agent_id": "agt_abc123xyz",
      "agent_path": "/home/user/my-agent"
    }
  ]
)

​
Mounting a Private Git Agent

For agents sourced from private Git repositories, provide an authentication token: 
devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "agent_mount",
      "agent_name": "private-agent",
      "agent_path": "/home/user/private-agent",
      "auth_token": os.environ.get("GH_TOKEN")
    }
  ]
)

​
Agent Path Requirements

The agent_path parameter behavior depends on the agent source type:
Source Typeagent_pathBehavior
GitRequiredClones the repository to the specified path. If omitted, defaults to $HOME/{repo_name}.
ObjectRequiredUnpacks the object to the specified path.
npmIgnoredPackage is installed for user via npm install -g. The agent_path field is disregarded.
pipIgnoredPackage is installed for user via pip install --user. The agent_path field is disregarded.

​
Best Practices

  1. Use agent names for flexibility: Using agent_name allows you to update agents without changing your Devbox configuration.
  2. Use agent IDs for reproducibility: When you need exact version control, use agent_id to pin to a specific agent version.
  3. Secure your tokens: Use environment variables or Account Secrets for authentication tokens.
  4. Combine with setup commands: Use setup_commands to run any additional agent initialization after mounting.