The main concepts#

Limanix connects three things: a configuration file on your Mac, a Linux virtual machine, and a set of NixOS modules that describe its tools and services.

Mac and VM are separate systems#

Term	Meaning	What you do there
Host	Your Mac, running macOS	Edit files and run `limanix` commands
Guest	The Linux system inside the VM	Compile, test, and run Linux programs
VM	The virtual machine containing the guest	Give it CPU, memory, a disk, and a name
Mount	A host directory made visible at a guest path	Work on the same project files from both systems

A mount does not copy your project. If you mount the project at /workspace, your editor on macOS and a compiler in Linux see the same files. With a read-write mount, deleting a file from the guest also deletes the host file.

        flowchart TD
    subgraph Mac["Mac · host"]
        Editor["Editor and project files"]
        CLI["Limanix CLI"]
        TOML["limanix.toml"]
    end
    subgraph VM["VM · Linux guest"]
        Workspace["/workspace"]
        Tools["Tools and services"]
        NixOS["NixOS system"]
    end
    Editor <-->|"shared mount"| Workspace
    TOML --> CLI
    CLI -->|"create or update"| NixOS
    NixOS --> Tools

Throughout these guides, Mac means your normal terminal. VM means the shell opened by limanix shell NAME. Use exit to return to the Mac.

What Lima and NixOS do#

Component	Job
Limanix	Reads TOML, manages VM operations, and prepares the guest configuration
Lima	Runs the Linux VM, connects to it, and shares directories
NixOS	Configures the Linux system from declarations
Nix	Evaluates those declarations and builds or obtains their dependencies
Nixpkgs	Supplies packages and NixOS options used by modules
NixOS module	A Nix file that contributes packages, services, or other system settings

Lima is integrated into the client. You do not need a separate Lima or Nix installation on macOS. The installation guide covers the additional host requirements when the guest uses a different CPU architecture.

Describe the result, then apply it#

For example, this selection asks the guest to include Git and Node.js:

[nixos]
modules = ["lmx:git", "lmx:nodejs"]

It is a fragment of a configuration, not a complete first-run file. Use the getting-started example for a complete environment.

Limanix combines the selected modules with its base NixOS configuration. The base handles guest integration, the development user, mounts, environment, and firewall settings. A module adds to that system; it does not replace the base.

The configuration is declarative: it states which tools and settings should be present. Editing the file alone does not change a running guest. On your Mac, apply the new declaration:

limanix update --config limanix.toml

This rebuilds the guest configuration and restarts the VM. It does not run on every shell connection. See Work with VMs for the exact lifecycle and what happens when an operation fails.

Three kinds of input#

Input	Owns	Example
Project TOML	VM resources, module selection, mounts, guest environment, ports	`resources.mem = "4GiB"`
Bundled catalog	Modules shipped inside this client binary	`lmx:git`
Imported module directory	Your own guest configuration	`third-party:my-tools`

The client copies imported modules into a local registry. A VM receives a new snapshot of the selected modules during creation or update. Editing an original module directory does not change either copy automatically.

The client also embeds the base NixOS flake and its lock file. You select or import modules through the CLI; there is no TOML field for replacing the entire flake. Start with Choose and manage modules when you need custom guest behavior.

Configuration is not your data#

The VM disk holds the Linux system and guest-only files. The development user's home is a separate directory on your Mac. Project mounts point to other host directories you chose.

These locations behave differently on deletion:

Location	Default `limanix delete NAME`
VM disk	Removed
Managed development home	Preserved
Mounted project directories	Left in place

Keeping TOML and modules in Git helps recreate the declared environment. It does not back up a database, a VM disk, or files in your home. Continue with Getting started, then read Storage and recovery before removing a VM.

The main concepts

Contents