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. Ignored for npm and pip agents. |
auth_token | No | Authentication token for private Git repositories |
agent_setup_commands | No | Additional setup commands to run after the agent is installed. These run in addition to any setup commands defined on the agent itself. |
agent_launch_args | No | Arguments 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.
| Agent | Description |
|---|
claude-code | Anthropic’s Claude Code |
codex | OpenAI’s Codex |
opencode | Open-source coding agent |
gemini-cli | Google’s Gemini CLI |
deepagents | DeepAgents 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.
devbox = await runloop.devbox.create(
mounts=[
{
"type": "agent_mount",
"agent_name": "claude-code"
}
]
)
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 Type | agent_path | Behavior |
|---|
| Git | Required | Clones the repository to the specified path. If omitted, defaults to $HOME/{repo_name}. |
| Object | Required | Unpacks the object to the specified path. |
| npm | Ignored | Package is installed for user via npm install -g. The agent_path field is disregarded. |
| pip | Ignored | Package is installed for user via pip install --user. The agent_path field is disregarded. |
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.
