Skip to main content
Tools are configured in an agent’s toolsets array. Each entry is an object with at minimum a type field. 
agents:
  root:
    toolsets:
      - type: filesystem
      - type: shell
      - type: memory
        path: ./dev.db

​
Built-in tools

Built-in tools are included with docker-agent and require no external dependencies.
TypeDescriptionPage
filesystemRead, write, list, search, and navigate filesFilesystem
shellExecute shell commandsShell
thinkReasoning scratchpad (no side effects)Think
todoTask list managementTodo
memoryPersistent key-value storage (SQLite)Memory
fetchHTTP requestsFetch
scriptCustom shell scripts exposed as toolsScript
lspLanguage Server Protocol integrationLSP
apiCustom HTTP API toolsAPI
user_promptInteractive user input promptsUser Prompt
transfer_taskDelegate to sub-agents (auto-enabled with sub_agents)Transfer Task
background_agentsDispatch sub-agents in parallelBackground Agents
handoffA2A remote agent delegationHandoff
a2aConnect to an A2A remote agentA2A

​
Common toolset fields

The following fields apply to all toolset types:
​
type
string
required
The toolset type. See the table above for all valid values.
​
tools
string[]
Whitelist of tool names to expose from this toolset. If omitted, all tools from the toolset are available. See Tool filtering.
​
instruction
string
Additional instructions injected into the agent’s system prompt when this toolset is loaded. Useful for guiding how and when to use the tools.
​
model
string
Override the model used for turns that process results from this toolset. Enables per-toolset model routing. Value can be a named model or inline provider/model string.
​
defer
boolean | string[]
Defer tool loading until first use. Pass true to defer all tools, or a list of tool names to defer specific tools. See Deferred tool loading.

​
Filesystem-specific fields

​
post_edit
array
List of commands to run after a file is edited. Each entry has path (glob pattern to match file paths) and cmd (shell command to execute).
​
ignore_vcs
boolean
When true, the filesystem tool ignores VCS files (e.g., .gitignore rules). Default is to respect VCS.

​
Memory-specific fields

​
path
string
Path to the SQLite database file for persistent storage. Default is an in-memory database.

​
Shell-specific fields

​
env
object
Environment variables to set for shell commands. Key-value pairs.

​
Script-specific fields

​
shell
object
Map of script tool definitions. Each key becomes the tool name. See Script tool for full options.

​
Todo-specific fields

​
shared
boolean
default:"false"
When true, the todo list is shared across all agents in the session.

​
Fetch-specific fields

​
timeout
number
HTTP request timeout in seconds.

​
API-specific fields

​
api_config
object
HTTP API tool definition. See API tool for full options.

​
LSP-specific fields

​
command
string
The LSP server command to run.
​
file_types
string[]
File extensions this LSP server handles (e.g., [".go", ".ts"]).
​
version
string
Package reference for auto-installing the LSP binary. Format: owner/repo or owner/repo@version.

​
MCP tools

Extend agents with external tools via the Model Context Protocol. Run MCP servers as secure Docker containers via the MCP Gateway: 
toolsets:
  - type: mcp
    ref: docker:duckduckgo      # web search
  - type: mcp
    ref: docker:github-official # GitHub integration
    tools: ["list_issues", "create_issue"]
Browse available tools at the Docker MCP Catalog.
​
ref
string
Docker MCP reference in docker:name format.
​
config
any
MCP server-specific configuration passed during initialization.

​
Local MCP (stdio)

Run MCP servers as local processes communicating over stdin/stdout: 
toolsets:
  - type: mcp
    command: python
    args: ["-m", "mcp_server"]
    tools: ["search", "fetch"]
    env:
      API_KEY: value
​
command
string
Command to execute the MCP server process.
​
args
string[]
Command-line arguments passed to the MCP server.
​
env
object
Environment variables for the MCP server process.
​
version
string
Package reference for auto-installing the command binary. Format: owner/repo or owner/repo@version. Set to "false" or "off" to disable auto-install.

​
Remote MCP (SSE / Streamable HTTP)

Connect to MCP servers over the network: 
toolsets:
  - type: mcp
    remote:
      url: "https://mcp-server.example.com"
      transport_type: "sse"
      headers:
        Authorization: "Bearer your-token"
    tools: ["search_web", "fetch_url"]
​
remote.url
string
Base URL of the remote MCP server.
​
remote.transport_type
string
Transport protocol: sse or streamable.
​
remote.headers
object
HTTP headers sent with every request (typically for authentication).

​
Reusable MCP definitions

Define MCP servers once in the top-level mcps section and reference them from multiple agents: 
mcps:
  github:
    ref: docker:github-official
    tools: ["list_issues", "create_issue", "get_pull_request"]

  search:
    ref: docker:duckduckgo

agents:
  root:
    toolsets:
      - type: mcp
        ref: github     # references the mcps section
      - type: mcp
        ref: search

​
Tool filtering

Use the tools property to expose only a subset of tools from a toolset. This reduces context window usage and improves tool selection accuracy: 
toolsets:
  - type: mcp
    ref: docker:github-official
    tools: ["list_issues", "create_issue", "get_pull_request"]
  - type: filesystem
    tools: ["read_file", "search_files_content"]
  - type: shell
    tools: ["shell"]
Filtering tools improves agent performance — fewer tools means less confusion for the model about which one to use.

​
Deferred tool loading

Deferred tools are loaded on-demand rather than at startup. This reduces startup time when you have many toolsets, especially slow-initializing MCP servers: 
toolsets:
  - type: mcp
    ref: docker:github-official
    defer: true          # all tools deferred
  - type: mcp
    ref: docker:slack
    defer: true
  - type: filesystem     # loaded immediately
Defer specific tools within a toolset: 
toolsets:
  - type: mcp
    ref: docker:github-official
    defer:
      - "list_issues"
      - "search_repos"

​
Auto-installing tools

When a toolset specifies a command (for MCP or LSP), docker-agent can automatically download and install the binary if it is not found on your PATH. Resolution order:
  1. Check PATH for the command
  2. Check the docker-agent tools directory (~/.cagent/tools/bin/)
  3. Look up the command in the aqua registry and install it
Specify an explicit package reference with version: 
toolsets:
  - type: mcp
    command: gopls
    version: "golang/[email protected]"
    args: ["mcp"]
The format is owner/repo or owner/repo@version. When version is omitted, the latest release is used.
VariableDefaultDescription
DOCKER_AGENT_AUTO_INSTALLenabledSet to false to disable all auto-installation
DOCKER_AGENT_TOOLS_DIR~/.cagent/tools/Base directory for installed tools
GITHUB_TOKEN—Raises GitHub API rate limits (optional)
Disable auto-install for a specific toolset: 
toolsets:
  - type: mcp
    command: my-custom-server
    version: "false"  # disables auto-install for this toolset
If multiple toolsets expose a tool with the same name, the first one wins. Order your toolsets intentionally.

​
Combined example

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: Full-featured developer assistant
    instruction: You are an expert developer.
    toolsets:
      # Built-in tools
      - type: filesystem
      - type: shell
      - type: think
      - type: todo
      - type: memory
        path: ./dev.db
      - type: user_prompt

      # LSP for code intelligence
      - type: lsp
        command: gopls
        file_types: [".go"]

      # Custom shell scripts as tools
      - type: script
        shell:
          run_tests:
            description: Run the test suite
            cmd: task test
          lint:
            description: Run the linter
            cmd: task lint

      # Docker MCP tools
      - type: mcp
        ref: docker:github-official
        tools: ["list_issues", "create_issue"]
        defer: true
      - type: mcp
        ref: docker:duckduckgo

      # Remote MCP
      - type: mcp
        remote:
          url: "https://internal-api.example.com/mcp"
          transport_type: "sse"
          headers:
            Authorization: "Bearer ${INTERNAL_TOKEN}"

Build docs developers (and LLMs) love

Get started for freeTalk to us