Reach services in the VM#

Limanix gives the guest its own IP address on a shared/NAT network. From your Mac, connect to that address and the service's port.

Three things must agree: the service must run, it must listen on a reachable guest interface, and the guest firewall must allow the port.

        flowchart TD
    accTitle: Connect from the Mac to a guest service
    accDescr: A Mac application connects to the guest IP and port through the shared network and the guest firewall. The service must listen on a guest network interface.
    mac["Mac: browser or client"] --> address["Guest IP:8080"]
    address --> firewall["Guest firewall: TCP 8080"]
    firewall --> service["Service listening on 0.0.0.0:8080"]

Open a service port#

For a service using TCP port 8080, set:

[network]
mode = "shared"

[network.ports]
tcp = [8080]
udp = []

shared is the only supported network.mode. Port numbers must be integers between 1 and 65535.

Apply the change to an existing VM:

limanix update --config ./limanix.toml

Start your application inside the guest using its own command. Configure it to listen on 0.0.0.0:8080 or the guest's network address. An application bound only to 127.0.0.1:8080 accepts connections from inside the guest.

On the Mac, find the guest address:

limanix list

Read the VM's ADDRESS column, then open http://<guest-ip>:8080 in your browser if the application speaks HTTP. Replace <guest-ip> with the reported address.

Ports are firewall rules#

Setting or action	What it does
`tcp = [8080]`	Allows inbound TCP port `8080` through the guest firewall.
`udp = [5353]`	Allows inbound UDP port `5353` through the guest firewall.
`tcp = []` or `udp = []`	Adds no openings from that configuration field.
Start an application	Creates the listener that can accept connections.

The lists do not install or start services. They do not map a Mac port to a guest port. Limanix disables Lima's automatic application port forwarding: localhost:8080 on the Mac is not an alias for the VM's port 8080.

Base NixOS configuration and selected modules can add their own firewall rules. An empty port list is therefore not a promise that every guest port is closed.

Choose the guest architecture#

Limanix chooses the VM backend from the guest architecture and the Mac's hardware:

Mac hardware	`resources.arch`	Backend	Network
Apple Silicon	`arm64`	Apple Virtualization framework (VZ)	Native NAT
Intel	`amd64`	Apple Virtualization framework (VZ)	Native NAT
Apple Silicon	`amd64`	QEMU	Lima shared network using `socket_vmnet`
Intel	`arm64`	QEMU	Lima shared network using `socket_vmnet`

Use the Limanix binary for your Mac's hardware in all four cases. Running the Intel Limanix binary under Rosetta on Apple Silicon is rejected for VM operations. To create an Intel guest on Apple Silicon, use the arm64 client and select resources.arch = "amd64" in the VM configuration.

The matching-architecture VZ path does not require QEMU or socket_vmnet. The client build must include the native VZ driver.

Prepare QEMU networking when needed#

For a different-architecture guest, install QEMU and make the appropriate executable available in PATH:

Guest architecture	Required executable
`amd64`	`qemu-system-x86_64`
`arm64`	`qemu-system-aarch64`

Then run this as your regular Mac user in an interactive terminal:

limanix network setup

Limanix checks the existing Lima network setup first. When installation is needed, it shows the helper and sudoers paths and asks for confirmation before invoking sudo.

Setup item	Location
Bundled network helper	`/opt/socket_vmnet/bin/socket_vmnet`
Lima sudoers rules	`/private/etc/sudoers.d/lima`

An existing sudoers file is backed up before replacement. The helper is installed when missing; an existing helper must pass the setup checks. Limanix and QEMU continue running as the regular user.

Creating or updating a QEMU guest also checks this setup and can offer the same interactive installation. A noninteractive command reports that setup is required instead of asking for approval.

Automatic installation supports Lima's standard helper, runtime, and sudoers paths. If the diagnostic reports custom paths, preserve that setup and have its administrator configure the helper and authorization for those paths.

Check a connection in order#

Read the VM status. Run limanix list. A stopped VM cannot accept the connection. ADDRESS = - means Limanix could not report a guest address; it does not identify the cause by itself.
Open a guest shell. Run limanix shell project-box. If this fails, resolve the reported VM or SSH error before debugging your application.
Check the application. Confirm it started successfully, uses the expected port, and listens on a guest network interface. Guest localhost is only reachable from the guest.
Check the matching protocol. An HTTP server normally needs its TCP port in network.ports.tcp; opening the same number under udp is a different rule.
Apply the current file. After editing firewall settings, run limanix update --config ./limanix.toml, wait for it to finish, and read limanix list again before retrying the reported IP address.

The address reported by list comes from the running guest's shared network interface. It is not a configured static address. Use the current value rather than copying an address from an earlier session.

See Work with VMs for power commands and the distinction between backend status and the last configuration operation.

Reach services in the VM

Contents