This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

AI

1: AI agents inside Lima

2: AI agents outside Lima (MCP)

2.1: Gemini
2.2: MCP tools

There are two kinds of scenario to use Lima with AI:

AI agents inside Lima: running an AI agent inside a VM
AI agents outside Lima: calling Lima’s MCP tools from an AI agent running outside a VM

1 - AI agents inside Lima

Lima is useful for running AI agents (e.g., Codex, Claude, Gemini) so as to prevent them from directly reading, writing, or executing the host files.

Lima v2.0 is planned to be released with built-in templates for well-known AI agents.

For Lima v1.x, you can install AI agents in Lima manually.

e.g.,

lima sudo apt install -y npm
lima sudo npm install -g @google/gemini-cli
lima gemini

2 - AI agents outside Lima (MCP)

Starting with Lima v2.0, Lima provides Model Context Protocol (MCP) tools for reading, writing, and executing local files using a VM sandbox.

2.1 - Gemini

⚡ Requirement	Lima >= 2.0

This page describes how to use Lima as an sandbox for Google Gemini CLI.

Prerequisite

In addition to Gemini and Lima, make sure that limactl mcp plugin is installed:

$ limactl mcp -v
limactl-mcp version 2.0.0-alpha.1

The limactl mcp plugin is bundled in Lima since v2.0, however, it may not be installed depending on the method of the installation.

Configuration

Run the default Lima instance, with a mount of your project directory:

limactl start --mount-only "$(pwd):w" default

Drop the :w suffix if you do not want to allow writing to the mounted directory.

Create .gemini/extensions/lima/gemini-extension.json as follows:

{
  "name": "lima",
  "version": "2.0.0",
  "mcpServers": {
    "lima": {
      "command": "limactl",
      "args": [
        "mcp",
        "serve",
        "default"
      ]
    }
  }
}

Modify .gemini/settings.json so as to disable Gemini CLI’s built-in tools except ones that do not relate to local command execution and file I/O:

{
  "coreTools": ["WebFetchTool", "WebSearchTool", "MemoryTool"]
}

Usage

Just run gemini in your project directory.

Gemini automatically recognizes the MCP tools provided by Lima.

2.2 - MCP tools

Lima implements the “MCP Sandbox Interface” (tentative name): https://pkg.go.dev/github.com/lima-vm/lima/v2/pkg/mcp/msi

MCP Sandbox Interface defines MCP (Model Context Protocol) tools that can be used for reading, writing, and executing local files with an appropriate sandboxing technology, such as Lima.

The sandboxing technology can be more secure and/or efficient than the default tools provided by an AI agent.

MCP Sandbox Interface was inspired by Google Gemini CLI’s built-in tools.

`glob`

Description

Finds files matching specific glob patterns (e.g., src/**/*.ts, *.md)

Input Schema

{
    "additionalProperties": false,
    "properties": {
        "path": {
            "description": "The absolute path to the directory to search within. If omitted, searches the tool's root directory.",
            "type": [
                "null",
                "string"
            ]
        },
        "pattern": {
            "description": "The glob pattern to match against (e.g., '*.py', 'src/**/*.js').",
            "type": "string"
        }
    },
    "required": [
        "pattern"
    ],
    "type": "object"
}

Output Schema

{
    "additionalProperties": false,
    "properties": {
        "matches": {
            "description": "A list of absolute file paths that match the provided glob pattern.",
            "items": {
                "type": "string"
            },
            "type": "array"
        }
    },
    "required": [
        "matches"
    ],
    "type": "object"
}

`list_directory`

Description

Lists the names of files and subdirectories directly within a specified directory path.

Input Schema

{
    "additionalProperties": false,
    "properties": {
        "path": {
            "description": "The absolute path to the directory to list.",
            "type": "string"
        }
    },
    "required": [
        "path"
    ],
    "type": "object"
}

Output Schema

{
    "additionalProperties": false,
    "properties": {
        "entries": {
            "description": "The directory content entries.",
            "items": {
                "additionalProperties": false,
                "properties": {
                    "is_dir": {
                        "description": "true for a directory",
                        "type": [
                            "null",
                            "boolean"
                        ]
                    },
                    "mode": {
                        "description": "file mode bits",
                        "type": [
                            "null",
                            "integer"
                        ]
                    },
                    "name": {
                        "description": "base name of the file",
                        "type": "string"
                    },
                    "size": {
                        "description": "length in bytes for regular files; system-dependent for others",
                        "type": [
                            "null",
                            "integer"
                        ]
                    },
                    "time": {
                        "description": "modification time",
                        "type": "string"
                    }
                },
                "required": [
                    "name"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "entries"
    ],
    "type": "object"
}

`read_file`

Description

Reads and returns the content of a specified file.

Input Schema

{
    "additionalProperties": false,
    "properties": {
        "path": {
            "description": "The absolute path to the file to read.",
            "type": "string"
        }
    },
    "required": [
        "path"
    ],
    "type": "object"
}

Output Schema

{
    "additionalProperties": false,
    "properties": {
        "content": {
            "description": "The content of the file.",
            "type": "string"
        }
    },
    "required": [
        "content"
    ],
    "type": "object"
}

`run_shell_command`

Description

Executes a given shell command.

Input Schema

{
    "additionalProperties": false,
    "properties": {
        "command": {
            "description": "The exact shell command to execute. Defined as a string slice, unlike Gemini's run_shell_command that defines it as a single string.",
            "items": {
                "type": "string"
            },
            "type": "array"
        },
        "description": {
            "description": "A brief description of the command's purpose, which will be potentially shown to the user.",
            "type": "string"
        },
        "directory": {
            "description": "The absolute directory in which to execute the command. Unlike Gemini's run_shell_command, this must not be a relative path, and must not be empty.",
            "type": "string"
        }
    },
    "required": [
        "command",
        "directory"
    ],
    "type": "object"
}

Output Schema

{
    "additionalProperties": false,
    "properties": {
        "error": {
            "description": "Any error message reported by the subprocess.",
            "type": "string"
        },
        "exit_code": {
            "description": "Exit code of the command.",
            "type": [
                "null",
                "integer"
            ]
        },
        "stderr": {
            "description": "Output from the standard error stream.",
            "type": "string"
        },
        "stdout": {
            "description": "Output from the standard output stream.",
            "type": "string"
        }
    },
    "required": [
        "stdout",
        "stderr"
    ],
    "type": "object"
}

`search_file_content`

Description

Searches for a regular expression pattern within the content of files in a specified directory. Internally calls ‘git grep -n –no-index’.

Input Schema

{
    "additionalProperties": false,
    "properties": {
        "include": {
            "description": "A glob pattern to filter which files are searched (e.g., '*.js', 'src/**/*.{ts,tsx}'). If omitted, searches most files (respecting common ignores).",
            "type": [
                "null",
                "string"
            ]
        },
        "path": {
            "description": "The absolute path to the directory to search within. Defaults to the current working directory.",
            "type": [
                "null",
                "string"
            ]
        },
        "pattern": {
            "description": "The regular expression (regex) to search for (e.g., 'function\\s+myFunction').",
            "type": "string"
        }
    },
    "required": [
        "pattern"
    ],
    "type": "object"
}

Output Schema

{
    "additionalProperties": false,
    "properties": {
        "git_grep_output": {
            "description": "The raw output from the 'git grep -n --no-index' command, containing matching lines with filenames and line numbers.",
            "type": "string"
        }
    },
    "required": [
        "git_grep_output"
    ],
    "type": "object"
}

`write_file`

Description

Writes content to a specified file. If the file exists, it will be overwritten. If the file doesn’t exist, it (and any necessary parent directories) will be created.

Input Schema

{
    "additionalProperties": false,
    "properties": {
        "content": {
            "description": "The content to write into the file.",
            "type": "string"
        },
        "path": {
            "description": "The absolute path to the file to write to.",
            "type": "string"
        }
    },
    "required": [
        "path",
        "content"
    ],
    "type": "object"
}

Output Schema

{
    "additionalProperties": false,
    "type": "object"
}