Frequently Asked Questions¶

Common questions about Mooncake and their answers.

General Questions¶

What is Mooncake?¶

Mooncake is a configuration management tool designed specifically for AI agents and modern development workflows. It provides a safe, validated execution environment for system configuration with idempotency guarantees, dry-run validation, and full observability.

Think of it as "the standard runtime for AI system configuration" - similar to how Docker provides a standard runtime for containers.

Why "Mooncake"?¶

The name comes from the show "Final Space" where mooncakes are a beloved treat. Also, configuration management should be as delightful as eating mooncakes! Chookity!

Is Mooncake production-ready?¶

Yes! Mooncake is actively used for:

Personal dotfiles management
Development environment setup
System provisioning
AI agent configuration tasks

It has comprehensive test coverage, runs on multiple platforms, and follows semantic versioning.

Comparison Questions¶

How is Mooncake different from Ansible?¶

Feature	Mooncake	Ansible
Target Audience	AI agents, developers, dotfiles	Enterprise infrastructure
Installation	Single binary, zero dependencies	Python + pip packages + galaxy collections
Setup	None required	Inventory files, host management
Complexity	Simple YAML	Complex playbooks, roles, collections
AI-Friendly	Designed for AI generation	Complex for AI to generate correctly
Dry-run	Built-in, always available	Check mode (limited)
Learning Curve	Minutes	Hours to days

When to use Mooncake:

AI agent configuration tasks
Personal dotfiles and dev environments
Simple automation scripts
Cross-platform configurations
When you want zero dependencies

When to use Ansible:

Large-scale enterprise infrastructure
Complex role-based architectures
Existing Ansible investments
Multi-host orchestration

How is Mooncake different from shell scripts?¶

Feature	Mooncake	Shell Scripts
Idempotency	Guaranteed	Manual
Dry-run	Native	Manual implementation
Error Handling	Built-in	Manual
Cross-platform	Unified syntax	OS-specific scripts
Validation	Schema validation	None
Variables	Built-in with facts	Manual

Mooncake provides:

Automatic idempotency
Built-in dry-run mode
Schema validation
Cross-platform abstractions
Structured error handling
System fact detection

Can I migrate from Ansible to Mooncake?¶

Yes! Mooncake uses similar YAML syntax. See the Migration Guide for details.

Common migrations:

Ansible playbook:

- hosts: localhost
  tasks:
    - name: Install package
      apt:
        name: neovim
        state: present
      become: yes

Mooncake equivalent:

- name: Install package
  shell: apt install -y neovim
  become: true
  when: package_manager == "apt"

AI & LLM Questions¶

Can AI agents use Mooncake safely?¶

Yes! Mooncake was designed specifically for AI agents:

Safe by Default: Dry-run mode lets AI preview changes before applying
Validated Operations: Schema validation prevents malformed configurations
Idempotency: Same config can be run multiple times safely
Full Observability: Structured events enable AI to understand execution
Simple Format: YAML is easy for AI models to generate and parse

How do AI models generate Mooncake configs?¶

Use the AI Specification: See AI Specification for a complete guide LLMs can follow

Provide system context:

# Give AI the system facts
mooncake facts --format json > facts.json

Let AI generate config:

# AI generates based on request and facts
- name: Install development tools
  shell: {{package_manager}} install {{item}}
  with_items: [git, vim, curl]
  become: true
  when: os == "linux"

Validate before executing:

# AI can validate without risk
mooncake run --config config.yml --dry-run

What's the AI agent workflow?¶

1. User Request → AI Agent
2. AI generates Mooncake config
3. AI runs dry-run to validate
4. AI shows preview to user
5. User approves
6. AI executes configuration
7. AI observes results via events

Security Questions¶

Is it safe to give AI agents sudo access?¶

Mooncake provides several safety layers:

Dry-run First: Always preview with --dry-run
Explicit sudo: Only steps with become: true get sudo
Password Control: You control sudo password access
Validation: Schema validation prevents malformed commands
Audit Trail: Full logging of all operations

Best practices:

Always review dry-run output before executing
Use tags to limit execution scope
Run sensitive operations manually
Monitor execution logs

How do I handle secrets?¶

Option 1: Environment Variables

- name: Use secret
  shell: echo "API_KEY=$API_KEY"
  environment:
    API_KEY: "{{ lookup('env', 'API_KEY') }}"

Option 2: Password Files

# Load from secure file
- include_vars:
    file: ~/.mooncake/secrets.yml

- name: Use secret
  shell: echo "{{api_key}}"

Option 3: External Secret Management

# Fetch from vault/keychain
- name: Get secret
  shell: security find-generic-password -s myapp -w
  register: secret
  no_log: true

- name: Use secret
  shell: curl -H "Authorization: {{secret.stdout}}"

Never:

Commit secrets to version control
Print secrets in logs (no_log: true)
Use plain text passwords in configs

Can I restrict what AI agents can do?¶

Yes, several ways:

Tags: Limit execution to specific operations

# AI can only run setup tasks
- name: Setup step
  shell: setup.sh
  tags: [setup]

mooncake run --config config.yml --tags setup

Conditional Execution: Restrict by facts

# Only allow dev operations
- name: Dev task
  shell: install-dev-tools.sh
  when: environment == "dev"

File Permissions: Control config access with file permissions
Sudo Control: Control sudo password access

Technical Questions¶

What languages/tools does Mooncake support?¶

Built-in language version managers:

Python (pyenv)
Node.js (nvm)
Ruby (rbenv)
Go (direct install)
Rust (rustup)
Java (OpenJDK)

Package managers detected automatically:

apt, dnf, yum, zypper, pacman, apk (Linux)
brew, port (macOS)
choco, scoop (Windows)

See all presets:

mooncake presets list

Does Mooncake work on Windows?¶

Yes! Mooncake supports Windows with some limitations:

Fully supported:

Shell commands (PowerShell/cmd)
File operations
Variable expansion
Templates
Downloads

Limited support:

Service management (basic Windows services)
Package management (via choco)

Use conditionals for cross-platform configs:

- name: Unix command
  shell: ls -la
  when: os != "windows"

- name: Windows command
  shell: dir
  when: os == "windows"

Can I use Mooncake in CI/CD?¶

Yes! Mooncake works great in CI/CD:

# Disable interactive TUI
mooncake run --config config.yml --raw

# JSON output for parsing
mooncake run --config config.yml --raw --output-format json

# Exit codes
# 0 = success
# 1+ = failure

Example GitHub Actions:

- name: Install Mooncake
  run: go install github.com/alehatsman/mooncake@latest

- name: Run configuration
  run: mooncake run --config config.yml --raw

- name: Verify
  run: mooncake facts

Does Mooncake support remote hosts?¶

Not yet. Mooncake currently executes on localhost only. Remote execution is planned for a future release.

For now, you can:

Copy config to remote host and run locally
Use SSH wrapper scripts
Wait for remote execution support (coming soon!)

Can I create my own presets?¶

Yes! Presets are just YAML files:

Create preset structure:

mkdir -p ~/.mooncake/presets/mypreset
cat > ~/.mooncake/presets/mypreset/preset.yml <<EOF
name: mypreset
version: "1.0.0"
description: My custom preset

parameters:
  - name: state
    type: string
    default: present
    enum: [present, absent]

steps:
  - name: Install
    shell: echo "Installing with state={{parameters.state}}"
    when: parameters.state == "present"
EOF

Use it:

- preset: mypreset
  with:
    state: present

See Preset Authoring Guide for details.

Usage Questions¶

Can I use Mooncake for dotfiles?¶

Yes! Mooncake is excellent for dotfiles:

- name: Create config directories
  file:
    path: "{{item}}"
    state: directory
  with_items:
    - ~/.config/nvim
    - ~/.config/tmux
    - ~/.config/zsh

- name: Deploy dotfiles
  copy:
    src: "{{item.src}}"
    dest: "~/{{item.name}}"
  with_filetree: ./dotfiles
  when: item.is_dir == false

Benefits:

Idempotent (run multiple times safely)
Cross-platform (same config for macOS/Linux)
Dry-run before applying
Version control friendly

Can I use loops?¶

Yes! Two types:

List loops:

- name: Install packages
  shell: brew install {{item}}
  with_items:
    - neovim
    - ripgrep
    - fzf

File tree loops:

- name: Deploy configs
  copy:
    src: "{{item.src}}"
    dest: "~/{{item.name}}"
  with_filetree: ./configs
  when: item.is_dir == false

Can I split configs across multiple files?¶

Yes! Use include_vars and organize by topic:

Main config:

- include_vars:
    file: ./vars/dev-tools.yml

- include_vars:
    file: ./vars/languages.yml

- name: Install dev tools
  shell: brew install {{item}}
  with_items: "{{dev_tools}}"

vars/dev-tools.yml:

dev_tools:
  - neovim
  - ripgrep
  - fzf

How do I handle different environments (dev/staging/prod)?¶

Option 1: Environment-specific configs

mooncake run --config config-dev.yml
mooncake run --config config-prod.yml

Option 2: Variables

- vars:
    environment: dev  # Change per environment

- name: Dev-only task
  shell: install-dev-tools.sh
  when: environment == "dev"

Option 3: Tags

- name: Dev setup
  shell: setup-dev.sh
  tags: [dev]

- name: Prod deployment
  shell: deploy-prod.sh
  tags: [prod]

mooncake run --config config.yml --tags dev

Troubleshooting Questions¶

Why is my variable undefined?¶

Common causes:

Variable not defined:

# Wrong
- shell: echo "{{my_var}}"

# Right
- vars:
    my_var: value
- shell: echo "{{my_var}}"

Using system fact incorrectly:

# Wrong - no such fact
- shell: echo "{{operating_system}}"

# Right - use 'os'
- shell: echo "{{os}}"

Variable scope issue - variables are scoped to the config file

Check available facts:

mooncake facts

Why does my step keep running (not idempotent)?¶

Some operations aren't idempotent by default:

Problem:

# Runs every time
- shell: echo "test" >> /tmp/file

Solutions:

Use idempotent actions:

- file:
    path: /tmp/file
    state: file
    content: "test"  # Idempotent

Use creates condition:

- shell: echo "test" > /tmp/file
  args:
    creates: /tmp/file  # Only if doesn't exist

Use changed_when:

- shell: echo "test" >> /tmp/file
  register: result
  changed_when: false  # Never report as changed

How do I debug template errors?¶

Check variable values:

- name: Debug variable
  shell: echo "Value is {{my_var}}"

Test template separately:

# Create test template
echo "{{ my_var }}" > test.j2

# Test with mooncake
mooncake run --config test-template.yml

Use simpler templates first:

# Start simple
- template:
    dest: /tmp/test
    content: "{{ simple_var }}"

# Then add complexity
- template:
    src: complex.j2
    dest: /tmp/test

Performance Questions¶

Is Mooncake fast?¶

Yes! Mooncake is written in Go and has minimal overhead:

Binary size: ~20MB
Startup time: <100ms
Memory usage: <50MB typically
No interpreter overhead (unlike Python-based tools)

Can I run steps in parallel?¶

Not yet. Steps currently run sequentially for safety and predictability. Parallel execution is planned for a future release.

How do I make my configs faster?¶

Remove unnecessary operations:

# Slow - updates package cache every time
- shell: apt update && apt install {{item}}
  with_items: [vim, git, curl]

# Fast - update once
- shell: apt update
- shell: apt install -y {{item}}
  with_items: [vim, git, curl]

Use tags to run only what's needed:

mooncake run --config config.yml --tags quick

Use creates/removes for idempotency:

- shell: tar xzf large-file.tar.gz
  args:
    creates: /opt/app/bin/app  # Skip if already extracted

Contributing Questions¶

How can I contribute?¶

Contributions are welcome!

Report bugs: GitHub Issues
Request features: GitHub Issues
Submit PRs: See Contributing Guide
Share presets: Submit to the presets repository
Improve docs: Documentation PRs always welcome!

What's the roadmap?¶

See the Roadmap for planned features:

Remote host execution
Parallel step execution
Enhanced service management
More built-in actions
Plugin system