Skip to content

Core Concepts

Mooncake configurations are YAML files containing an array of steps. Each step performs one action.

Two-Phase Architecture

Mooncake uses a two-phase architecture for configuration execution:

  1. Planning Phase - Expands configuration into a deterministic plan
  2. Resolves all includes recursively
  3. Expands all loops (with_items, with_filetree) into individual steps
  4. Tracks origin (file:line:col) for every step
  5. Filters steps by tags (marked as skipped)

  6. Produces a deterministic, inspectable plan

  7. Execution Phase - Executes the plan

  8. Evaluates when conditions at runtime
  9. Executes actions (shell, file, template, etc.)
  10. Captures results and updates variables
  11. Logs progress and status

Benefits:

  • Deterministic - Same config always produces the same plan
  • Inspectable - Use mooncake plan to see what will execute
  • Traceable - Every step tracks its origin with include chain
  • Debuggable - Understand loop expansions and includes before execution

Steps

Steps are executed sequentially:

- name: First step
  shell: echo "hello"

- name: Second step
  file:
    path: /tmp/test
    state: directory

Actions

Available actions:

  • shell / command - Execute shell commands or direct commands
  • file - Create files, directories, links, and manage permissions
  • copy - Copy files with checksum verification
  • download - Download files from URLs with checksums and retry
  • unarchive - Extract tar.gz, zip archives with security protections
  • template - Render configuration templates
  • package - Install, remove, and update system packages
  • service - Manage system services (systemd on Linux, launchd on macOS)
  • assert - Verify state (command results, file properties, HTTP responses)
  • preset - Invoke reusable, parameterized workflows (e.g., ollama preset)
  • print - Display messages to the user
  • include - Load other configuration files
  • include_vars - Load variables from files
  • vars - Define variables

Variables

Use {{variable}} syntax for dynamic values:

- vars:
    app_name: MyApp

- shell: echo "Installing {{app_name}}"

System Facts

Automatically available variables:

  • os - Operating system (linux, darwin, windows)
  • arch - Architecture (amd64, arm64)
  • hostname - System hostname
  • distribution - Linux/macOS distribution

See all facts: mooncake facts

Next

Continue to Commands to learn about CLI usage.