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

# Mount AI Agents

> Mount pre-configured AI agents to your Devboxes

<Tip>Start with the [Runloop Quickstart](/docs/tutorials/quickstart) to use the examples below.</Tip>

## 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:

<CodeGroup>
  ```python Python theme={null}
  devbox = await runloop.devbox.create(
    mounts=[
      {
        "type": "agent_mount",
        "agent_name": "my-coding-agent",
        "agent_path": "/home/user/agent"
      }
    ]
  )
  ```

  ```typescript TypeScript theme={null}
  const devbox = await runloop.devbox.create({
    mounts: [
      {
        type: "agent_mount",
        agent_name: "my-coding-agent",
        agent_path: "/home/user/agent"
      }
    ]
  });
  ```
</CodeGroup>

### 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                                                                                              |

<Note>
  Either `agent_id` or `agent_name` must be provided, but not both. Using `agent_name` will mount the most recent agent with that name.
</Note>

## 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           |

<Note>
  Each agent requires API keys to authenticate with its underlying LLM provider. Use [Agent Gateways](/docs/devboxes/agent-gateways#using-agent-gateways-with-llm-clients) to securely provide these keys without exposing them inside the devbox.
</Note>

<Warning>
  **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.
</Warning>

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

<CodeGroup>
  ```python Python theme={null}
  devbox = await runloop.devbox.create(
    mounts=[
      {
        "type": "agent_mount",
        "agent_name": "claude-code"
      }
    ]
  )
  ```

  ```typescript TypeScript theme={null}
  const devbox = await runloop.devbox.create({
    mounts: [
      {
        type: "agent_mount",
        agent_name: "claude-code"
      }
    ]
  });
  ```
</CodeGroup>

You can also list available public agents using the API:

<CodeGroup>
  ```python Python theme={null}
  public_agents = await runloop.agent.list_public()
  for agent in public_agents.agents:
      print(f"{agent.name} v{agent.version}")
  ```

  ```typescript TypeScript theme={null}
  const publicAgents = await runloop.agent.listPublic();
  publicAgents.agents?.forEach(agent => {
      console.log(`${agent.name} v${agent.version}`);
  });
  ```
</CodeGroup>

## Examples

### Mounting an Agent by Name

When you specify `agent_name`, Runloop will find the most recent agent with that name:

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```typescript TypeScript theme={null}
  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());
  ```
</CodeGroup>

### Mounting an Agent by ID

For precise version control, use the agent's ID:

<CodeGroup>
  ```python Python theme={null}
  devbox = await runloop.devbox.create(
    mounts=[
      {
        "type": "agent_mount",
        "agent_id": "agt_abc123xyz",
        "agent_path": "/home/user/my-agent"
      }
    ]
  )
  ```

  ```typescript TypeScript theme={null}
  const devbox = await runloop.devbox.create({
    mounts: [
      {
        type: "agent_mount",
        agent_id: "agt_abc123xyz",
        agent_path: "/home/user/my-agent"
      }
    ]
  });
  ```
</CodeGroup>

### Mounting a Private Git Agent

For agents sourced from private Git repositories, provide an authentication token:

<CodeGroup>
  ```python Python theme={null}
  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")
      }
    ]
  )
  ```

  ```typescript TypeScript theme={null}
  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
      }
    ]
  });
  ```
</CodeGroup>

## 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

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](/docs/devboxes/configuration/account-secrets) for authentication tokens.
4. **Combine with setup commands**: Use `setup_commands` to run any additional agent initialization after mounting.