Skip to main content

Quick Start

This walkthrough uses the official lumi recipe for Minecraft Bedrock Edition. For Java, run nesk search --edition java and substitute the selected recipe name in the same workflow.

1. Install and check the environment​

Linux or macOS:

curl -fsSL https://nesk.farin.cc/sh | sh -s -- --yes

Windows AMD64 (x64), PowerShell:

irm https://nesk.farin.cc/ps1 | iex

The self-contained installer does not require Python. The Unix --yes belongs only to this installer; it does not accept the Minecraft EULA or approve later server operations. For uv, pipx, ZIP bundle, update, removal, and PATH details, see Installation.

Check the installed CLI and Docker:

nesk --version
nesk doctor
docker version

2. Discover and inspect​

nesk catalog update
nesk catalog status
nesk search --type core
nesk search lumi --type core --edition bedrock
nesk info lumi

Catalog entries are discovery metadata, not an automatic trust decision. Open the referenced recipe repository and inspect luminesk.toml and any declared Dockerfile.

3. Preview and install​

For a guided installation, let the input wizard collect memory and other recipe settings, then review the trust plan before confirming:

nesk install lumi --dir ./servers/example

For automation, provide inputs and trust approval explicitly:

nesk install lumi --dir ./servers/example --dry-run
nesk install lumi --dir ./servers/example --yes

An official catalog name installs the exact recipe associated with the active catalog entry. For a direct GitHub recipe, use OWNER/RECIPE@REF or --ref REF to select a branch, tag, or commit. The installed lockfile records the exact commit. The target must be empty for a remote or external local recipe.

In human mode the wizard shows every recipe input with its prompt, type, default, and constraints. --dry-run resolves, builds, and prints the unified preview without applying it. The preview includes trust, capabilities, pinned artifacts, runtime image, and every planned file change. A dry-run never asks for trust approval because it does not apply the plan. For the real installation, --yes accepts this exact preview. The Lumi recipe has no eula input. For recipes that require EULA acceptance, supply it separately; --yes only approves the plan.

Long operations display a spinner and a short status on interactive stderr. If the terminal appears quiet because output is redirected or JSON mode is active, use --debug to see stage transitions without exposing input values.

Official recipes default their non-root container identity to UID/GID 1000. On Linux accounts with another identity, add --set runtime_uid=$(id -u) --set runtime_gid=$(id -g) to the install command.

4. Run the instance and open its console​

nesk start --dir ./servers/example
nesk status --dir ./servers/example
nesk attach --dir ./servers/example
nesk logs --dir ./servers/example

When inside the instance directory, --dir may be omitted. start waits for declared readiness checks unless --no-wait is explicitly provided.

attach opens with the latest 200 log lines and follows new output. Type a server command and press Enter. Ctrl+D exits the TUI without stopping the server, Ctrl+C stops it gracefully, and Ctrl+K kills it.

Editable server configs are normally generated by the server during this first start rather than seeded as partial files by the recipe. To change one, stop the server first, edit the complete generated file in the instance directory, then start it again:

nesk stop --dir ./servers/example
# Edit ./servers/example/settings.yml generated by Lumi.
nesk start --dir ./servers/example

Connect from Minecraft Bedrock Edition using the server host and UDP port 19132, as declared by the Lumi recipe.

5. Find the instance and preview an update​

nesk list
nesk outdated --dir ./servers/example
nesk diff --dir ./servers/example
nesk update --dir ./servers/example --dry-run
nesk update --dir ./servers/example --yes

An update stops a running instance, applies the planned package transaction, starts it again, waits for readiness, and restores the previous instance if a required step fails. Keep independent backups for production data even though the recipe also declares transaction backup paths.

If an interrupted transaction cannot recover automatically, run:

nesk recover --dir ./servers/example
nesk validate --dir ./servers/example --instance

Next, read Server Lifecycle and Recipes and Updates. Recipe authors can continue with Manifest and Lockfile.