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 Type | Description | Example |
|---|
| Git | Clone an agent from a Git repository | Open source agents, custom agents |
| NPM | Install an agent from npm registry | Node.js-based agents |
| PIP | Install an agent from PyPI | Python-based agents |
| Object | Unpack an agent from a storage object | Pre-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
| Parameter | Required | Description |
|---|
type | Yes | Must be "agent_mount" |
agent_id | No* | The ID of the agent to mount |
agent_name | No* | The name of the agent to mount (uses most recent version) |
agent_path | Depends | Path where the agent should be mounted. Required for Git and Object agents. |
auth_token | No | Authentication token for private Git repositories |
Either agent_id or agent_name must be provided, but not both. Using agent_name will mount the most recent agent with that name.
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 Type | agent_path Required | Default Behavior |
|---|
| Git | Yes | Must specify where to clone |
| Object | Yes | Must specify where to unpack |
| NPM | No | Installed globally via npm |
| PIP | No | Installed globally via pip |
For Git agents, if no agent_path is provided, the agent will be cloned to a directory named after the repository in the user’s home directory.
Best Practices
- Use agent names for flexibility: Using
agent_name allows you to update agents without changing your Devbox configuration.
- Use agent IDs for reproducibility: When you need exact version control, use
agent_id to pin to a specific agent version.
- Secure your tokens: Use environment variables or Account Secrets for authentication tokens.
- Combine with setup commands: Use
setup_commands to run any additional agent initialization after mounting.
