Plain mode: support port forwarding #3699

Horiodino · 2025-07-06T17:20:46Z

Fixes #2962

Changes

Added --port-forward CLI flag to limactl create, allowing users to specify static port forwards even in plain mode.
Modified host agent to set up static SSH-based TCP port forwarding in plain mode.
Updated YAML expressions to handle portForwards from CLI.
Added validation warnings for large port ranges in plain mode.

cmd/limactl/editflags/editflags.go

pkg/hostagent/hostagent.go

pkg/limayaml/defaults.go

templates/default.yaml

nirs

It is not clear what is the suggested behavior. Can we start with the documentation instead of the code, so we have clear understanding of wanted behavior?

cmd/limactl/editflags/editflags.go

pkg/hostagent/hostagent.go

cmd/limactl/editflags/editflags.go

hack/test-nonplain-static-port-forward.sh

hack/test-plain-static-port-forward.sh

templates/default.yaml

hack/test-templates/plain-static-port-forward.yaml

hack/test-templates/nonplain-static-port-forward.yaml

Copilot

Pull Request Overview

Adds support for user-defined static port forwarding in plain mode by extending the CLI, YAML schema, host agent logic, and validation.

Introduce a --port-forward flag with parsing and YQ expression generation
Extend PortForward with Static, filter non-static rules in plain mode, and warn on large port ranges
Update host agent to separate/apply static forwards and add end-to-end tests + CI jobs

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/portfwd/forward.go	Skip dynamic forwarding for statically handled ports
pkg/limayaml/validate.go	Warn for port ranges >10 in plain mode
pkg/limayaml/limayaml.go	Add `Static` field to `PortForward` struct
pkg/limayaml/defaults.go	Remove non-static forwards when plain mode is enabled
pkg/limayaml/defaults_test.go	Tests for filtering static vs. non-static forwards
pkg/hostagent/hostagent.go	Separate and apply static forwards; adjust event loop logic
cmd/limactl/editflags/editflags.go	Register `port-forward` flag and implement parsing & expression
cmd/limactl/editflags/editflags_test.go	Unit tests for `ParsePortForward` and `BuildPortForwardExpression`
hack/test-templates/static-port-forward.yaml	Template covering static/dynamic port examples
hack/test-plain-static-port-forward.sh	Script to verify static-only forwarding in plain mode
hack/test-nonplain-static-port-forward.sh	Script to verify full forwarding in normal mode
.github/workflows/test.yml	CI jobs to run the new static port forwarding tests

Comments suppressed due to low confidence (2)

pkg/hostagent/hostagent.go:619

[nitpick] Consider adding unit or integration tests for separateStaticPortForwards and addStaticPortForwardsFromList to verify correct separation and application of static port-forwarding rules.

func (a *HostAgent) addStaticPortForwardsFromList(ctx context.Context, staticPortForwards []limayaml.PortForward) {

pkg/hostagent/hostagent.go:642

The loop uses for i := range len(a.instConfig.PortForwards), which attempts to range over an int and will not compile. Change it to for i := range a.instConfig.PortForwards or use a classic indexed loop like for i := 0; i < len(...); i++.

	for i := range len(a.instConfig.PortForwards) {

pkg/hostagent/hostagent.go

.github/workflows/test.yml

cmd/limactl/editflags/editflags.go

AkihiroSuda · 2025-08-18T04:25:07Z

Needs rebase

pkg/hostagent/hostagent.go

AkihiroSuda · 2025-08-29T02:23:19Z

@Horiodino Could you rebase?

AkihiroSuda · 2025-09-02T07:25:45Z

resolve merge conflicts

This kind of commit can be squashed:

https://lima-vm.io/docs/dev/git/#squashing-commits

AkihiroSuda · 2025-09-02T07:26:13Z

Also, GPG signature seems invalid

The email in this signature doesn’t match the committer email.
GPG key ID: EB539798A4127F9F

Signed-off-by: Praful Khanduri <99384392+Horiodino@users.noreply.github.com>

Signed-off-by: Praful Khanduri <holiodin@gmail.com>

AkihiroSuda

Thanks

norio-nomura · 2025-09-04T01:37:03Z

Are there any reasons not to support guestSocket and hostSocket on static?

norio-nomura · 2025-09-04T02:06:03Z

~~The test~~ Some tests added here do not seem to be running in CI.

norio-nomura · 2025-09-04T02:17:52Z

hack/test-templates.sh

 	set +x
 fi

+if [[ -n ${CHECKS["static-port-forwards"]} ]]; then


Is this test performed in CI?

norio-nomura · 2025-09-08T07:23:13Z

hack/test-plain-static-port-forward.sh

+
+limactl shell $INSTANCE -- bash -c 'until [ -e /run/nginx.pid ]; do sleep 1; done'
+
+curl -sSf http://127.0.0.1:9090 | grep -i 'nginx' && echo 'Static port forwarding (9090) works in plain mode!'


This line does not stop on error, because && disable set -e

bash-5.3$ bash -c 'set -e; false && echo 1; echo 2; false; echo 3' 2

This test script is unreliable.
In fact, even if static: true, it will not be forwarded.

norio-nomura · 2025-09-08T07:23:28Z

pkg/hostagent/hostagent.go

+		if err != nil {
+			errs = append(errs, err)
+		}
+		a.addStaticPortForwardsFromList(ctx, staticPortForwards)


a.addStaticPortForwardsFromList() is only called when --plain=false, so it does not work as intended when --plain=true.

filed #4002

Hey @norio-nomura, thanks for pointing that out sorry for the inconvenience! I’ll get it fixed .

⚠️ **CAUTION: this is a major update, indicating a breaking change!** ⚠️ This MR contains the following updates: | Package | Update | Change | |---|---|---| | [lima-vm/lima](https://github.com/lima-vm/lima) | major | `v1.2.2` -> `v2.0.1` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>lima-vm/lima (lima-vm/lima)</summary> ### [`v2.0.1`](https://github.com/lima-vm/lima/releases/tag/v2.0.1) [Compare Source](lima-vm/lima@v2.0.0...v2.0.1) #### Changes - Binary release artifacts: - Fix a regression in v2.0.0 `level=fatal msg="template \"_images/<IMAGE>.yaml\" not found"` ([#4313](lima-vm/lima#4313), thanks to [@vvoland](https://github.com/vvoland)) - Misc: - pkg/networks/usernet: use `SIGINT` instead of `SIGKILL` ([#4310](lima-vm/lima#4310), thanks to [@norio-nomura](https://github.com/norio-nomura)) Full changes: <https://github.com/lima-vm/lima/milestone/64?closed=1> #### Usage ```console $ limactl create $ limactl start ... INFO[0029] READY. Run `lima` to open the shell. $ lima uname Linux ``` *** The binaries were built automatically on GitHub Actions. The build log is available for 90 days: <https://github.com/lima-vm/lima/actions/runs/19137304035> The sha256sum of the SHA256SUMS file itself is `25ad222fa1cf91a85ef7be67664f2ba65228a5d82a39be1adbbe842096854e24` . *** Release manager: [@AkihiroSuda](https://github.com/AkihiroSuda) ### [`v2.0.0`](https://github.com/lima-vm/lima/releases/tag/v2.0.0) [Compare Source](lima-vm/lima@v1.2.2...v2.0.0) This is the second major release of Lima, featuring the support for [pluggable VM drivers](https://lima-vm.io/docs/dev/drivers/), [GPU acceleration](https://lima-vm.io/docs/config/gpu/), and [MCP](https://lima-vm.io/docs/config/ai/outside/mcp/). This release also commemorates the promotion of the project from CNCF [Sandbox](https://www.cncf.io/sandbox-projects/) to [Incubating](https://www.cncf.io/projects/) 🎉. #### Highlights - [Experimental plug-in subsystem for VM driver infrastructure](https://lima-vm.io/docs/dev/drivers/). This will help implementing third-party plugins without modifying the code base of Lima. Thanks to [GSoC 2025](https://gist.github.com/unsuman/ff31a323ecef2289bf065882726ed7f0) contributor [@unsuman](https://github.com/unsuman) . - [Experimental krunkit VM driver](https://lima-vm.io/docs/config/vmtype/krunkit/) for supporting GPU acceleration ([#4137](lima-vm/lima#4137), thanks to [@unsuman](https://github.com/unsuman)) - [Experimental integration for Model Context Protocol (MCP)](https://lima-vm.io/docs/config/ai/outside/) ([#3744](lima-vm/lima#3744)). i.e., Lima can be now used as a sandbox for AI agents such as Gemini. - Add `limactl (start|restart) --progress` flag to show the progress of provisioning ([#3846](lima-vm/lima#3846), [#3915](lima-vm/lima#3915), thanks to [@olamilekan000](https://github.com/olamilekan000) [@norio-nomura](https://github.com/norio-nomura)) - Add `limactl shell --preserve-env` flag to propagate env vars from the host to VM ([#3830](lima-vm/lima#3830), thanks to [@olamilekan000](https://github.com/olamilekan000)) #### Other notable changes - `/tmp/lima` is no longer mounted by default ([#3951](lima-vm/lima#3951)) - SSH port is no longer hard-coded to 60022 for the "default" instance ([#3780](lima-vm/lima#3780)) - Forward UDP ports by default ([#4054](lima-vm/lima#4054)) - Support CLI plugins ([#3834](lima-vm/lima#3834), [#4009](lima-vm/lima#4009), thanks to [@olamilekan000](https://github.com/olamilekan000)) - Support custom URL scheme plugins ([#3937](lima-vm/lima#3937), thanks to [@jandubois](https://github.com/jandubois)). `template://default` is now recommended to be written as `template:default`. The old form is still supported. ##### Details - VM driver infrastructure: - [Experimental plug-in subsystem for VM driver infrastructure](https://lima-vm.io/docs/dev/drivers/) ([multiple MRs](https://github.com/lima-vm/lima/pulls?q=is%3Apr+milestone%3Av2.0.0+is%3Aclosed+label%3Aarea%2Fvmdrivers), thanks to [@unsuman](https://github.com/unsuman)) - krunkit: - [Experimental krunkit VM driver](https://lima-vm.io/docs/config/vmtype/krunkit/) for supporting GPU acceleration ([#4137](lima-vm/lima#4137), thanks to [@unsuman](https://github.com/unsuman)) - VZ: - Support Rosetta AOT Caching with CDI ([#3858](lima-vm/lima#3858), thanks to [@norio-nomura](https://github.com/norio-nomura)) - Support accelerating SSH using `AF_VSOCK` ([#3979](lima-vm/lima#3979), thanks to [@norio-nomura](https://github.com/norio-nomura)) - QEMU: - Fallback to TCG when KVM is not available on Linux hosts ([#4204](lima-vm/lima#4204)) - MCP: - [Experimental integration for Model Context Protocol (MCP)](https://lima-vm.io/docs/config/ai/outside/) ([#3744](lima-vm/lima#3744)). Lima now provides MCP tools for reading, writing, and executing local files using a VM sandbox. Known to work with Google Gemini CLI. - `limactl` CLI: - Add `limactl (start|restart) --progress` flag to show the progress of provisioning ([#3846](lima-vm/lima#3846), [#3915](lima-vm/lima#3915), thanks to [@olamilekan000](https://github.com/olamilekan000) [@norio-nomura](https://github.com/norio-nomura)) - Add `limactl (create|start|edit) --port-forward` flag for static port forwarding ([#3699](lima-vm/lima#3699), thanks to [@Horiodino](https://github.com/Horiodino)). Usually not needed, but useful for instances created with `--plain`. - Add `limactl (create|start|edit) --ssh-port` flag ([#3791](lima-vm/lima#3791)) - Add `limactl (create|start|edit) --mount-only` flag ([#3947](lima-vm/lima#3947)). Similar to `--mount`, but overrides the existing mounts. Useful for mounting `$(pwd)`. - Support specifying `--set` multiple times in `limactl (create|start|edit)` ([#4197](lima-vm/lima#4197), thanks to [@AndiDog](https://github.com/AndiDog)) - Add `limactl shell --preserve-env` flag to propagate env vars from the host to VM ([#3830](lima-vm/lima#3830), thanks to [@olamilekan000](https://github.com/olamilekan000)). See also [`LIMA_SHELLENV_ALLOW`](https://lima-vm.io/docs/config/environment-variables/#lima_shellenv_allow) and [`LIMA_SHELLENV_BLOCK`](https://lima-vm.io/docs/config/environment-variables/#lima_shellenv_block). - Support CLI plugins ([#3834](lima-vm/lima#3834), [#4009](lima-vm/lima#4009), thanks to [@olamilekan000](https://github.com/olamilekan000)) - Support custom URL scheme plugins ([#3937](lima-vm/lima#3937), thanks to [@jandubois](https://github.com/jandubois)). `template://default` is now recommended to be written as `template:default`. The old form is still supported. - Add `limactl copy --backend=rsync` flag as an alternative to `scp` backend ([#3143](lima-vm/lima#3143), thanks to [@olamilekan000](https://github.com/olamilekan000)) - Add `limactl list--yq` and `limactl info --yq` flags ([#3998](lima-vm/lima#3998), thanks to [@jandubois](https://github.com/jandubois)) - Add `limactl rename OLD NEW` ([#4207](lima-vm/lima#4207)) - Deprecate `--yes` and introduce `limactl (clone|rename|edit|shell) --start` instead ([#4108](lima-vm/lima#4108), [#4285](lima-vm/lima#4285), thanks to [@Horiodino](https://github.com/Horiodino) [@nlordell](https://github.com/nlordell)) - YAML: - Migrate `cpuType` to `vmOpts.qemu` ([#3500](lima-vm/lima#3500), thanks to [@unsuman](https://github.com/unsuman)) - Add `yq` provision mode ([#3892](lima-vm/lima#3892), thanks to [@norio-nomura](https://github.com/norio-nomura)) - Prohibit relative paths in YAML ([#3950](lima-vm/lima#3950)). Relative paths were never intended to be supported, but they were accidentally allowed due to a regression in v1.1.0. The CLI command `limactl (create|start|edit) --mount DIR` still supports relative paths. - Default template: - Remove `/tmp/lima` mount ([#3951](lima-vm/lima#3951)) - Stop hardcoding SSH port 60022 ([#3780](lima-vm/lima#3780)) - Network: - Enable mDNS for vzNAT and socket\_vmnet ([#4272](lima-vm/lima#4272), thanks to [@norio-nomura](https://github.com/norio-nomura)) - Port forwarding: - Support port forwarding in plain mode ([#3699](lima-vm/lima#3699), thanks to [@Horiodino](https://github.com/Horiodino)) - Support host sockets in gRPC port forwarder ([#4008](lima-vm/lima#4008), thanks to [@norio-nomura](https://github.com/norio-nomura)) - Forward UDP ports by default ([#4054](lima-vm/lima#4054)) - Eliminated 3-second delay for detecting ports ([#4066](lima-vm/lima#4066)) - Removed iptables watcher for `sudo nerdctl run -p ...` ([#4107](lima-vm/lima#4107)). `sudo nerdctl run -p ...` now requires nerdctl v2.1.6 or later. - Improved performance of gRPC forwarder ([#4247](lima-vm/lima#4247), thanks to [@balajiv113](https://github.com/balajiv113)) - Support UDP in Kubernetes ([#4233](lima-vm/lima#4233)) - Change default of `guestIPMustBeZero` to `true` when `guestIP` is `0.0.0.0` ([#4221](lima-vm/lima#4221), thanks to [@jandubois](https://github.com/jandubois)) - Build system: - Remove `Kconfig` and `config.mk`, in favor of Makefile variables ([#3732](lima-vm/lima#3732)) - Support Fedora, RHEL, and relevant host distributions ([#4228](lima-vm/lima#4228), thanks to [@valdela1](https://github.com/valdela1)) - Templates: - `alpine`, `alpine-iso`: update to Alpine 3.22 ([#4184](lima-vm/lima#4184), [#4190](lima-vm/lima#4190), thanks to [@jandubois](https://github.com/jandubois)) - `debian`: update to Debian 13 ([#4029](lima-vm/lima#4029), thanks to [@unsuman](https://github.com/unsuman)) - `docker`, `docker-rootful`: Enable containerd image store ([#3941](lima-vm/lima#3941), thanks to [@norio-nomura](https://github.com/norio-nomura)) - `fedora`: update to Fedora 43 ([#4255](lima-vm/lima#4255)) - `opensuse`: update to openSUSE Leap 16 ([#4203](lima-vm/lima#4203)) - `oraclelinux`: update to Oracle Linux 10 ([#4236](lima-vm/lima#4236), thanks to [@valdela1](https://github.com/valdela1)) - `ubuntu`, `default`: update Ubuntu to 25.10 ([#4202](lima-vm/lima#4202)) - `k0s`: New template ([#3728](lima-vm/lima#3728), thanks to [@plandem](https://github.com/plandem)) - `experimental/ubuntu-next`: update to Ubuntu 26.04 pre-release ([#4311](lima-vm/lima#4311)) - Project: - Invite Ansuman Sahoo ([@unsuman](https://github.com/unsuman)) as a Reviewer ([#4003](lima-vm/lima#4003), thanks to [@jandubois](https://github.com/jandubois)) - Promote from CNCF Sandbox to Incubating ([#4201](lima-vm/lima#4201)) Full changes: <https://github.com/lima-vm/lima/milestone/59?closed=1> Thanks to [@AndiDog](https://github.com/AndiDog) [@Horiodino](https://github.com/Horiodino) [@afbjorklund](https://github.com/afbjorklund) [@alexandear](https://github.com/alexandear) [@ashwat287](https://github.com/ashwat287) [@balajiv113](https://github.com/balajiv113) [@bonifaido](https://github.com/bonifaido) [@dharsanb](https://github.com/dharsanb) [@gnawhleinad](https://github.com/gnawhleinad) [@iamleot](https://github.com/iamleot) [@jandubois](https://github.com/jandubois) [@kachick](https://github.com/kachick) [@muchzill4](https://github.com/muchzill4) [@ningmingxiao](https://github.com/ningmingxiao) [@nlordell](https://github.com/nlordell) [@norio-nomura](https://github.com/norio-nomura) [@olamilekan000](https://github.com/olamilekan000) [@plandem](https://github.com/plandem) [@stek29](https://github.com/stek29) [@unsuman](https://github.com/unsuman) [@valdela1](https://github.com/valdela1) [@vax-r](https://github.com/vax-r) [@vishalanarase](https://github.com/vishalanarase) [@zyfy29](https://github.com/zyfy29) #### EOL of v1.2 Lima v1.2 will continue to receive security updates and critical bug fixes until **2026-02-06** (3 months from now). See also <https://lima-vm.io/docs/releases/>. #### Usage ```console $ limactl create $ limactl start ... INFO[0029] READY. Run `lima` to open the shell. $ lima uname Linux ``` *** The binaries were built automatically on GitHub Actions. The build log is available for 90 days: <https://github.com/lima-vm/lima/actions/runs/19130682878> The sha256sum of the SHA256SUMS file itself is `112f1ef1d9850e29b4be425ca71e8b6ac686f593ff741164885b51fbd6919ca6` . *** Release manager: [@AkihiroSuda](https://github.com/AkihiroSuda) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

Horiodino force-pushed the port-forwarding branch from ac63182 to df5213b Compare July 6, 2025 17:27