Define "MCP Sandbox Interface" and implement `limactl mcp serve` #3744

AkihiroSuda · 2025-07-17T11:14:39Z

This PR allows AI agents such as Gemini CLI to wrap local file operations (read/write/execute) inside Lima VM.

It should work with Claude Code, Codex, etc. too, but they might need a modification to disable their built-in local file operation tools. (Help wanted for testing)

This feature will be available in Lima v2.0

v2.0 planning (pluggable VM drivers, AI helpers, etc.) #3712

Preview of the documentation: https://deploy-preview-3744--lima-vm.netlify.app/docs/config/ai/

Interface

pkg/mcp/msi defines "MCP Sandbox Interface" (tentative) that should be reusable for other projects too.

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. 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 Gemini CLI's built-in tools. https://github.com/google-gemini/gemini-cli/tree/v0.1.12/docs/tools

Implementation

limactl mcp serve INSTANCE launches an MCP server that implements the MCP Sandbox Interface.

Use https://github.com/modelcontextprotocol/inspector to play around with the server.

limactl start default
brew install mcp-inspector
mcp-inspector

In the web browser,

Set Command to limactl
Set Arguments to mcp serve default
Click ▶️Connect

Usage with Gemni CLI

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

TODOs

Support writing files
Test

AkihiroSuda · 2025-07-17T15:19:25Z

pkg/mcp/msi/msi.go

+//   - [RunShellCommandParams].Directory must not be empty
+//
+// Eventually, this package may be split to a separate repository.
+package msi


RFC: "MCP Sandbox Interface" might be a misnomer; it might rather sound like an interface for sandboxing MCP servers, e.g., docker run -i --rm example.com/some-mcp-server /usr/bin/some-mcp-server
https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#docker-based-mcp-server

Alternative names:

AI Sandbox Interface

Agent Sandbox Interface

AI Protection Interface

...

Thoughts?

cc @lima-vm/maintainers

jandubois · 2025-09-02T20:24:30Z

I've only browsed the code, but if I understand this correctly, the "protection" relies just on the fact that the VM has mounted the filesystem readonly. AFAICT there is no sandboxing of the filesystem, so the ReadFile tool could still read e.g. credentials from ~/.aws/config on the host and is not restricted to subdirectories of the current directory. And since you run arbitrary commands, this would need some kind of chroot jail, and not a pre-filtering of the arguments.

Beyond that, I wonder if this isn't outside the scope of Lima itself. It is an application built on top of Lima, but for some reason compiled into it. It could just as well be built as a separate tool. Or as a limactl-mcp plugin.

So I wonder if it wouldn't be good to include it as an example on how to create plugins for Lima? The reason to keep it in the Lima repo would be that MCP is a hot topic, and having it bundled makes it easier to discover.

AkihiroSuda · 2025-09-03T05:56:10Z

I've only browsed the code, but if I understand this correctly, the "protection" relies just on the fact that the VM has mounted the filesystem readonly. AFAICT there is no sandboxing of the filesystem, so the ReadFile tool could still read e.g. credentials from ~/.aws/config on the host and is not restricted to subdirectories of the current directory. And since you run arbitrary commands, this would need some kind of chroot jail, and not a pre-filtering of the arguments.

The home directory except the pwd can be hidden with:

limactl start --mount-only "$(pwd)"

editflags: add --mount-only flag #3947

Beyond that, I wonder if this isn't outside the scope of Lima itself. It is an application built on top of Lima, but for some reason compiled into it. It could just as well be built as a separate tool. Or as a limactl-mcp plugin.

Maybe lima-mcp (or lima-mcpserver) so as to keep limac[TAB] shell completion working ?

jandubois · 2025-09-03T19:17:21Z

Maybe lima-mcp (or lima-mcpserver) so as to keep limac[TAB] shell completion working ?

limactl-mcp would be the naming scheme we have already implemented. Tab completion still works, but you have to type the space yourself:

$ cat ~/bin/limactl-hello
#!/bin/bash
echo "Hello world from $BASH_SOURCE"

$ limactl hello
Hello world from /Users/jan/bin/limactl-hello

We could also look for plugins in /usr/local/share/libexec/lima to have an option to install them outside the PATH by default (we already look for external drivers in that directory).

AkihiroSuda · 2025-09-09T06:07:56Z

Reimplemented as limactl-mcp CLI plugin

jandubois · 2025-09-12T03:17:31Z

It doesn't seem to be working for me:

❯ l mcp -v
limactl-mcp version 2.0.0-alpha.0-39-gf71031e6

❯ l ls default qemu
NAME       STATUS     SSH                VMTYPE    ARCH       CPUS    MEMORY    DISK      DIR
default    Stopped    127.0.0.1:0        vz        aarch64    4       4GiB      100GiB    ~/.lima/default
qemu       Running    127.0.0.1:63754    qemu      aarch64    4       4GiB      100GiB    ~/.lima/qemu

❯ l mcp serve default
FATA[0000] expected status of instance "default" to be "Running", got ""

❯ l mcp serve qemu
FATA[0000] expected status of instance "qemu" to be "Running", got ""

❯ l shell qemu uname -a
Linux lima-qemu 6.14.0-23-generic #23-Ubuntu SMP PREEMPT_DYNAMIC Fri Jun 13 22:12:54 UTC 2025 aarch64 aarch64 aarch64 GNU/Linux

AkihiroSuda · 2025-09-12T20:35:15Z

It doesn't seem to be working for me:

Works for me.
Maybe you have some "non-standard" config? (e.g., custom LIMA_HOME)

jandubois · 2025-09-14T06:44:41Z

Maybe you have some "non-standard" config? (e.g., custom LIMA_HOME)

No, I have the default setup. My suspicion is that store.Inspect does not work properly because limactl-mcp doesn't have the builtin drivers, and I don't have the drivers installed as external drivers. So loading of the driver-specific fields does not work.

I would have expected to see something like vmType "vz" is not registered or something like that, so don't know if the theory is correct.

Are you sure you don't have external qemu and vz drivers installed on your system, that might be responsible for making it work on your machine.

I think as a plugin the code has to call limactl ls INSTANCE --json as a subprocess instead of using store.Inspect.

jandubois · 2025-09-14T06:51:53Z

Confirmed: The error goes away after running

ADDITIONAL_DRIVERS="qemu vz" make native additional-drivers limactl-plugins install

jandubois · 2025-09-14T17:35:37Z

I would have expected to see something like vmType "vz" is not registered or something like that,

And it turns out to be #2668 once again wasting time. We really should fix this non-idiomatic interface.

When I add

@@ -151,6 +152,9 @@ func mcpServeAction(cmd *cobra.Command, args []string) error {
 	if err != nil {
 		return err
 	}
+	if len(inst.Errors) != 0 {
+		return errors.Join(inst.Errors...)
+	}
 	if err = ts.RegisterInstance(ctx, inst); err != nil {
 		return err
 	}

then I get a more meaningful error:

❯ l mcp serve default
FATA[0000] failed to resolve vm for "/Users/jan/.lima/default/lima.yaml": vmType "vz" is not a registered driver

jandubois · 2025-09-15T01:43:03Z

Is it a bug that make uninstall does not remove external drivers?

unsuman · 2025-09-15T18:32:15Z

Is it a bug that make uninstall does not remove external drivers?

I guess for a dev env, make clean should remove the external drivers. Not sure how make uninstall works though?

jandubois · 2025-09-15T18:38:21Z

I guess for a dev env, make clean should remove the external drivers. Not sure how make uninstall works though?

You can just look it up in the Makefile. 😄

make clean just deletes _output with everything in it.

The install target actually runs uninstall first, to make sure it installs a consistent set of files. It tries do delete anything that has potentially been installed by make install before. I think we just forgot to add the external drivers to the uninstall target.

unsuman · 2025-09-15T18:57:53Z

Oh, got it, thanks! I've raised a fix for the same #4034

AkihiroSuda · 2025-09-18T04:18:54Z

Fixed the incompatibility with built-in drivers

=== Interface === `pkg/mcp/msi` defines "MCP Sandbox Interface" (tentative) that should be reusable for other projects too. 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. 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 Gemini CLI's built-in tools. https://github.com/google-gemini/gemini-cli/tree/v0.1.12/docs/tools === Implementation === `limactl mcp serve INSTANCE` launches an MCP server that implements the MCP Sandbox Interface. Use <https://github.com/modelcontextprotocol/inspector> to play around with the server. ```bash limactl start default brew install mcp-inspector mcp-inspector ``` In the web browser, - Set `Command` to `limactl` - Set `Arguments` to `mcp serve default` - Click `▶️Connect` === Usage with Gemni CLI === 1. Create `.gemini/extensions/lima/gemini-extension.json` as follows: ```json { "name": "lima", "version": "2.0.0", "mcpServers": { "lima": { "command": "limactl", "args": [ "mcp", "serve", "default" ] } } } ``` 2. 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: ```json { "coreTools": ["WebFetchTool", "WebSearchTool", "MemoryTool"] } ``` Signed-off-by: Akihiro Suda <[email protected]>

alexandear · 2025-09-18T09:15:13Z

website/content/en/docs/config/ai/lima-in-ai/gemini.md

+
+Drop the `:w` suffix if you do not want to allow writing to the mounted directory.
+
+1. Create `.gemini/extensions/lima/gemini-extension.json` as follows:


Suggested change

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

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

alexandear · 2025-09-18T09:15:20Z

website/content/en/docs/config/ai/lima-in-ai/gemini.md

+}
+```
+
+1. Modify `.gemini/settings.json` so as to disable Gemini CLI's [built-in tools](https://github.com/google-gemini/gemini-cli/tree/main/docs/tools)


Suggested change

1. Modify `.gemini/settings.json` so as to disable Gemini CLI's [built-in tools](https://github.com/google-gemini/gemini-cli/tree/main/docs/tools)

3. Modify `.gemini/settings.json` so as to disable Gemini CLI's [built-in tools](https://github.com/google-gemini/gemini-cli/tree/main/docs/tools)

alexandear · 2025-09-18T09:16:01Z

website/content/en/docs/config/ai/lima-in-ai/gemini.md

+---
+
+| ⚡ Requirement    | Lima >= 2.0 |
+|-------------------|-------------|


Suggested change

|-------------------|-------------|

|------------------|-------------|

alexandear · 2025-09-18T09:19:06Z

cmd/limactl-mcp/main.go

+		serverOpts.Instructions += fmt.Sprintf(`
+
+NOTE: the guest OS of the VM is Linux, while the host OS is %s.
+`, strings.ToTitle(runtime.GOOS))


strings.ToTitle(runtime.GOOS)) capitalizes all chars:

darwin -> DARWIN

windows -> WINDOWS

Do you think it is intentional?

alexandear · 2025-09-18T09:23:47Z

pkg/limactlutil/limactlutil.go

+	limactl := os.Getenv("LIMACTL")
+	if limactl == "" {
+		limactl = "limactl"
+	}


Can be slightly shorter:

Suggested change

limactl := os.Getenv("LIMACTL")

if limactl == "" {

limactl = "limactl"

}

limactl := cmp.Or(os.Getenv("LIMACTL"), "limactl")

alexandear · 2025-09-18T09:25:17Z

pkg/mcp/msi/filesystem.go

+
+var SearchFileContent = &mcp.Tool{
+	Name:        "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'.`,


Suggested change

Description: `searches for a regular expression pattern within the content of files in a specified directory. Internally calls 'git grep -n --no-index'.`,

Description: `Searches for a regular expression pattern within the content of files in a specified directory. Internally calls 'git grep -n --no-index'.`,

alexandear · 2025-09-18T09:34:55Z

pkg/mcp/toolset/toolset.go

+	ssh := append([]string{sshExe.Exe}, sshExe.Args...)
+	ssh = append(ssh, "-F",
+		filepath.Join(inst.Dir, filenames.SSHConfig),
+		hostname.FromInstName(inst.Name))
+
+	cmd := exec.CommandContext(ctx, ssh[0], append(ssh[1:], "-s", "sftp")...)


Maybe it's simpler with slices.Concat:

Suggested change

ssh := append([]string{sshExe.Exe}, sshExe.Args...)

ssh = append(ssh, "-F",

filepath.Join(inst.Dir, filenames.SSHConfig),

hostname.FromInstName(inst.Name))

cmd := exec.CommandContext(ctx, ssh[0], append(ssh[1:], "-s", "sftp")...)

args := slices.Concat(sshExe.Args, []string{"-F", filepath.Join(inst.Dir, filenames.SSHConfig), hostname.FromInstName(inst.Name), "-s", "sftp"})

cmd := exec.CommandContext(ctx, sshExe.Exe, args...)

AkihiroSuda added this to the v2.0.0 milestone Jul 17, 2025

AkihiroSuda added impact/changelog area/mcp labels Jul 17, 2025

This was referenced Jul 17, 2025

v2.0 planning (pluggable VM drivers, AI helpers, etc.) #3712

Open

Proposal: plugin API for sandboxing shell commands and file I/O google-gemini/gemini-cli#3216

Open

AkihiroSuda force-pushed the mcp branch from c599769 to 904302b Compare July 17, 2025 15:15

AkihiroSuda commented Jul 17, 2025

View reviewed changes

AkihiroSuda force-pushed the mcp branch 3 times, most recently from dadfb7c to ab6c5dc Compare July 17, 2025 15:36

AkihiroSuda force-pushed the mcp branch 2 times, most recently from 0892d60 to 2967ffe Compare September 2, 2025 05:34

jandubois mentioned this pull request Sep 4, 2025

Add a plugin mechanism to provide custom locator URL schemes #3937

Draft

AkihiroSuda force-pushed the mcp branch 2 times, most recently from 11ff941 to d8c61ec Compare September 9, 2025 06:06

AkihiroSuda force-pushed the mcp branch 2 times, most recently from 42eb5c5 to 206003b Compare September 9, 2025 08:21

AkihiroSuda marked this pull request as ready for review September 9, 2025 08:21

AkihiroSuda force-pushed the mcp branch from 206003b to f71031e Compare September 9, 2025 15:45

AkihiroSuda requested a review from jandubois September 10, 2025 00:10

unsuman mentioned this pull request Sep 15, 2025

Fix: make uninstall should remove external drivers #4034

Merged

jandubois closed this in #4034 Sep 16, 2025

AkihiroSuda reopened this Sep 16, 2025

AkihiroSuda marked this pull request as draft September 17, 2025 03:33

AkihiroSuda force-pushed the mcp branch from f71031e to e7f0085 Compare September 18, 2025 04:18

AkihiroSuda marked this pull request as ready for review September 18, 2025 04:18

AkihiroSuda force-pushed the mcp branch from e7f0085 to 89a36bc Compare September 18, 2025 04:27

alexandear reviewed Sep 18, 2025

View reviewed changes


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

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

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

	1. Modify `.gemini/settings.json` so as to disable Gemini CLI's [built-in tools](https://github.com/google-gemini/gemini-cli/tree/main/docs/tools)
	3. Modify `.gemini/settings.json` so as to disable Gemini CLI's [built-in tools](https://github.com/google-gemini/gemini-cli/tree/main/docs/tools)

	\|-------------------\|-------------\|
	\|------------------\|-------------\|

	Description: `searches for a regular expression pattern within the content of files in a specified directory. Internally calls 'git grep -n --no-index'.`,
	Description: `Searches for a regular expression pattern within the content of files in a specified directory. Internally calls 'git grep -n --no-index'.`,

Define "MCP Sandbox Interface" and implement limactl mcp serve #3744

Are you sure you want to change the base?

Define "MCP Sandbox Interface" and implement limactl mcp serve #3744

Uh oh!

Conversation

AkihiroSuda commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Interface

Implementation

Usage with Gemni CLI

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jandubois commented Sep 2, 2025

Uh oh!

AkihiroSuda commented Sep 3, 2025

Uh oh!

jandubois commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AkihiroSuda commented Sep 9, 2025

Uh oh!

jandubois commented Sep 12, 2025

Uh oh!

AkihiroSuda commented Sep 12, 2025

Uh oh!

jandubois commented Sep 14, 2025

Uh oh!

jandubois commented Sep 14, 2025

Uh oh!

jandubois commented Sep 14, 2025

Uh oh!

jandubois commented Sep 15, 2025

Uh oh!

unsuman commented Sep 15, 2025

Uh oh!

jandubois commented Sep 15, 2025

Uh oh!

unsuman commented Sep 15, 2025

Uh oh!

AkihiroSuda commented Sep 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Define "MCP Sandbox Interface" and implement `limactl mcp serve` #3744

Define "MCP Sandbox Interface" and implement `limactl mcp serve` #3744

AkihiroSuda commented Jul 17, 2025 •

edited

Loading

jandubois commented Sep 3, 2025 •

edited

Loading