From 638e3baf22cfd5979f192978487f56898c5c846b Mon Sep 17 00:00:00 2001
From: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
Date: Wed, 1 Oct 2025 20:54:32 +0900
Subject: [PATCH] docs: add examples for AI agents

Related to issue 4072

Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
---
 .../en/docs/config/ai/inside/_index.md        |  16 +--
 website/content/en/docs/examples/ai.md        | 121 ++++++++++++++++++
 2 files changed, 124 insertions(+), 13 deletions(-)
 create mode 100644 website/content/en/docs/examples/ai.md

diff --git a/website/content/en/docs/config/ai/inside/_index.md b/website/content/en/docs/config/ai/inside/_index.md
index 4356f5d0a81..02f78b7b261 100644
--- a/website/content/en/docs/config/ai/inside/_index.md
+++ b/website/content/en/docs/config/ai/inside/_index.md
@@ -3,17 +3,7 @@ title: AI agents inside Lima
 weight: 10
 ---
 
-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 is useful for running AI agents (e.g., Claude Code, Codex, Gemini)
+inside a VM, so as to prevent agents 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.,
-
-```bash
-lima sudo apt install -y npm
-lima sudo npm install -g @google/gemini-cli
-lima gemini
-```
\ No newline at end of file
+See [Examples » AI](../../../examples/ai.md).
\ No newline at end of file
diff --git a/website/content/en/docs/examples/ai.md b/website/content/en/docs/examples/ai.md
new file mode 100644
index 00000000000..da88e82e2b3
--- /dev/null
+++ b/website/content/en/docs/examples/ai.md
@@ -0,0 +1,121 @@
+---
+title: AI agents
+weight: 5
+---
+
+Lima is useful for running AI agents inside a VM, so as to prevent agents
+from directly reading, writing, or executing the host files.
+
+For running AI agents, it is highly recommended to only mount your project directory (current directory)
+into the VM:
+
+{{< tabpane text=true >}}
+{{% tab header="Lima v2.0+" %}}
+```bash
+limactl start --mount-only .:w
+```
+
+Drop `:w` for read-only mode.
+{{% /tab %}}
+{{% tab header="Lima v1.x" %}}
+```bash
+limactl start --set ".mounts=[{\"location\":\"$(pwd)\", \"writable\":true}]"
+```
+
+Set `writable` to `false` for read-only mode.
+{{% /tab %}}
+{{< /tabpane >}}
+
+<!--
+AI agents are sorted alphabetically.
+
+Node.js is installed via snap, not apt, as AI agents often require a very recent release of Node.js.
+-->
+{{< tabpane text=true >}}
+{{% tab header="Aider" %}}
+```
+lima sudo apt install -y pipx
+lima pipx install aider-install
+lima sh -c 'echo "export PATH=$PATH:$HOME/.local/bin" >>~/.bash_profile'
+lima aider-install
+lima aider
+```
+
+Follow the guide shown in the first session for authentication.
+
+Alternatively, you can set environmental variables via:
+```
+lima vi "/home/${USER}.linux/.bash_profile"
+```
+
+See also <https://github.com/Aider-AI/aider>.
+{{% /tab %}}
+{{% tab header="Claude Code" %}}
+```
+lima sudo snap install node --classic
+lima sudo npm install -g @anthropic-ai/claude-code
+lima codex
+```
+
+Follow the guide shown in the first session for authentication.
+
+Alternatively, you can set `export ANTHROPIC_API_KEY...` via:
+```
+lima vi "/home/${USER}.linux/.bash_profile"
+```
+
+See also <https://github.com/anthropics/claude-code>.
+{{% /tab %}}
+{{% tab header="Codex" %}}
+```
+lima sudo snap install node --classic
+lima sudo npm install -g @openai/codex
+lima codex
+```
+
+Follow the guide shown in the first session for authentication.
+
+Alternatively, you can set `export OPENAI_API_KEY...` via:
+```
+lima vi "/home/${USER}.linux/.bash_profile"
+```
+
+See also <https://github.com/openai/codex>.
+{{% /tab %}}
+{{% tab header="Gemini" %}}
+```
+lima sudo snap install node --classic
+lima sudo npm install -g @google/gemini-cli
+lima gemini
+```
+
+Follow the guide shown in the first session for authentication.
+
+Alternatively, you can set `export GEMINI_API_KEY...` via:
+```
+lima vi "/home/${USER}.linux/.bash_profile"
+```
+
+See also <https://github.com/google-gemini/gemini-cli>.
+{{% /tab %}}
+{{% tab header="GitHub Copilot" %}}
+```
+lima sudo snap install node --classic
+lima sudo npm install -g @github/copilot
+lima copilot
+```
+
+Type `/login` in the first session for authentication.
+
+Alternatively, you can set `export GH_TOKEN=...` via:
+```
+lima vi "/home/${USER}.linux/.bash_profile"
+```
+
+See also <https://github.com/github/copilot-cli>.
+{{% /tab %}}
+{{< /tabpane >}}
+
+## See also
+
+- [Config » AI](../config/ai/)