From 0393df3f385e0ada4a418592f957b315d778d3cf Mon Sep 17 00:00:00 2001
From: EclipseAditya <aditya75pandey@gmail.com>
Date: Sat, 29 Nov 2025 14:21:48 +0000
Subject: [PATCH] docs: explain usage of limactl tunnel with user-v2 network

Add documentation for using limactl tunnel to access VMs on the
user-v2 network from the host via a SOCKS proxy.

Fixes #4179

Signed-off-by: EclipseAditya <aditya75pandey@gmail.com>
---
 .../content/en/docs/config/network/user-v2.md | 44 ++++++++++++++++++-
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/website/content/en/docs/config/network/user-v2.md b/website/content/en/docs/config/network/user-v2.md
index c4710fd4bf0..611956ddc92 100644
--- a/website/content/en/docs/config/network/user-v2.md
+++ b/website/content/en/docs/config/network/user-v2.md
@@ -40,6 +40,46 @@ networks:
 
 An instance's IP address is resolvable from another instance as `lima-<NAME>.internal.` (e.g., `lima-default.internal.`).
 
-_Note_
+> **Note**
+>
+> Enabling user-v2 network will disable the [default user-mode network]({{< ref "/docs/config/network/user" >}}).
 
-- Enabling this network will disable the [default user-mode network]({{< ref "/docs/config/network/user" >}})
+## Accessing VMs from the host
+
+By default, the `lima-<NAME>.internal` hostnames are only resolvable from within the guest VMs.
+To access the guest network from the host, use `limactl tunnel` to create a SOCKS proxy:
+
+```bash
+limactl tunnel <INSTANCE>
+```
+
+The command will output the proxy address (the port is randomly assigned):
+```console
+$ limactl tunnel default
+Set `ALL_PROXY=socks5h://127.0.0.1:<PORT>`, etc.
+The instance can be connected from the host as <http://lima-default.internal> via a web browser.
+```
+
+You can then access any VM on the user-v2 network from the host using the SOCKS proxy:
+
+{{< tabpane text=true >}}
+{{% tab header="curl" %}}
+```bash
+curl --proxy socks5h://127.0.0.1:<PORT> http://lima-default.internal
+```
+{{% /tab %}}
+{{% tab header="Environment variable" %}}
+```bash
+export ALL_PROXY=socks5h://127.0.0.1:<PORT>
+curl http://lima-default.internal
+```
+{{% /tab %}}
+{{% tab header="Web browser" %}}
+Configure your browser to use the SOCKS5 proxy at `127.0.0.1:<PORT>`,
+then navigate to `http://lima-default.internal`.
+{{% /tab %}}
+{{< /tabpane >}}
+
+> **Note**
+>
+> `limactl tunnel` is experimental.