Getting started#

Create a small Linux environment, enter its shell, then add tools and share your project. Start with an installed native client.

1. Save a configuration#

On your Mac, make a new working directory:

mkdir limanix-demo
cd limanix-demo

Save this as limanix.toml. It uses Apple Silicon, creates a development user, and selects no optional modules or project mounts:

schema_version = 1
name = "dev-box"
mounts = []
env = {}

[user]
name = "dev"
home = "/home/dev"
sudo = true

[resources]
arch = "arm64"
cpu = 2
mem = "4GiB"
disk = "16GiB"

[home]
root = "~/.limanix"

[nixos]
modules = []

[network]
mode = "shared"

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

You can also download the file. On Intel, change arch to "amd64".

Setting	Effect
`name = "dev-box"`	Name used by lifecycle and shell commands
`cpu`, `mem`, `disk`	VM resources; `GiB` is the required memory and disk unit
`user`	Your Linux account; this example permits passwordless sudo inside the VM
`home.root`	Host directory beneath which Limanix creates this VM's managed home
`mounts = []`	No extra project directories are shared
`env = {}`	No extra environment variables
Empty module and port lists	Base guest system with no optional modules or additional firewall openings

The managed home is still shared even with mounts = []. The empty lists and table are intentional: omitted collections can retain the built-in example's values. Configuration explains these defaults.

limanix first-config is another way to write an editable example. It includes sample mounts that need review and overwrites an existing limanix.toml. For this walkthrough, use the explicit file above.

2. Create the VM#

Run on your Mac:

limanix create --config limanix.toml

Creation downloads the base image as needed, boots the guest, builds its NixOS configuration, and restarts it into that configuration. The first run needs network access and can take longer while dependencies are downloaded or built.

Wait for the command to finish successfully. It prints the VM name and the managed home's host path. Then inspect the environment:

limanix list
limanix shell dev-box

Inside the VM, check where you are:

uname -s
whoami
pwd

For this configuration, the expected results are Linux, dev, and /home/dev. Return to your Mac with exit.

3. Add development tools#

On your Mac, inspect the catalog embedded in your installed client:

limanix modules list

Select entries from that list. For a catalog containing Git and Node.js, replace the existing module list in limanix.toml:

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

Finish any guest work, then apply the change from your Mac:

limanix update --config limanix.toml
limanix shell dev-box -- git --version
limanix shell dev-box -- node --version

Updating restarts the VM. The new tools come from the selected modules; there is no separate installation command inside the guest for this workflow.

5. Pause and return#

Exit the guest shell. On your Mac:

limanix stop dev-box
limanix start dev-box
limanix shell dev-box

Stopping preserves the VM disk and host files. Starting boots the existing configuration; it does not read your edited TOML or refresh modules.

If you want to remove the demo, read Storage and recovery first. Deleting a VM removes its disk, while preserving its managed home by default.

Where to go next#

Configuration: users, resources, mounts, environment, and defaults.
Modules: bundled toolchains and your own NixOS configuration.
Work with VMs: updates, shell commands, and lifecycle states.
Troubleshooting: a failed create, update, or connection.

Getting started

Contents