Mount AI Agents

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 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"
    }
  ]
)

const 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.

Mount a public agent by name just like any other agent:

devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "agent_mount",
      "agent_name": "claude-code"
    }
  ]
)

const 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}")

const publicAgents = await runloop.agent.listPublic();
publicAgents.agents?.forEach(agent => {
    console.log(`${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())

const 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
const result = await devbox.cmd.exec("ls /home/user/code-reviewer");
console.log(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"
    }
  ]
)

const 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")
    }
  ]
)

const devbox = await runloop.devbox.create({
  mounts: [
    {
      type: "agent_mount",
      agent_name: "private-agent",
      agent_path: "/home/user/private-agent",
      auth_token: process.env.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.

Overview

Tools

Components

Benchmarks & Evals

Debugging

Overview

Agent Source Types

Creating an Agent Mount

Agent Mount Parameters

Public Agents

Examples

Mounting an Agent by Name

Mounting an Agent by ID

Mounting a Private Git Agent

Agent Path Requirements

Best Practices

​Overview

​Agent Source Types

​Creating an Agent Mount

​Agent Mount Parameters

​Public Agents

​Examples

​Mounting an Agent by Name

​Mounting an Agent by ID

​Mounting a Private Git Agent

​Agent Path Requirements

​Best Practices

Overview

Agent Source Types

Creating an Agent Mount

Agent Mount Parameters

Public Agents

Examples

Mounting an Agent by Name

Mounting an Agent by ID

Mounting a Private Git Agent

Agent Path Requirements

Best Practices