mooncake

module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 12, 2026 License: MIT

README

Mooncake

CI Security codecov

The Standard Runtime for AI System Configuration

Mooncake is to AI agents what Docker is to containers - a safe, validated execution layer for system configuration. Chookity!

Built for AI-driven infrastructure with idempotency guarantees, dry-run validation, and full observability.

- name: Hello Mooncake
  shell: echo "Running on {{os}}/{{arch}}"

- name: Create file
  file:
    path: /tmp/hello.txt
    state: file
    content: "Hello from Mooncake!"

Who It's For

AI Agent Developers - Build agents that configure systems safely with validated execution, observability, and compliance

Platform Engineers - Manage AI-driven infrastructure with audit trails and safety guardrails

Developers with AI Assistants - Let AI manage your dotfiles and dev setup with built-in safety and undo

DevOps Teams - Simpler alternative to Ansible for personal/team configs with AI workflow integration

Quick Start

# Install
go install github.com/alehatsman/mooncake@latest

# Create config.yml
cat > config.yml <<'EOF'
- name: Hello Mooncake
  shell: echo "Running on {{os}}/{{arch}}"

- name: Create file
  file:
    path: /tmp/hello.txt
    state: file
    content: "Hello from Mooncake!"
EOF

# Preview changes (safe!)
mooncake run --config config.yml --dry-run

# Run it
mooncake run --config config.yml

What You Can Do

Action Purpose Example
shell Run commands shell: echo "hello"
file Create files/directories file: {path: /tmp/test, state: directory}
template Render configs template: {src: app.j2, dest: /etc/app.conf}
copy Copy with checksums copy: {src: ./file, dest: /tmp/file}
download Fetch from URLs download: {url: https://..., dest: /tmp/file}
service Manage services service: {name: nginx, state: started}
assert Verify state assert: {command: {cmd: docker --version}}
preset Reusable workflows preset: ollama

Variables & Facts: Auto-detected system info - {{os}}, {{arch}}, {{cpu_cores}}, {{memory_total_mb}}, {{distribution}}, {{package_manager}}

mooncake facts  # See all available facts

Control Flow: Conditionals (when), loops (with_items, with_filetree), tags, sudo

Why AI Agents Choose Mooncake

  • Safe by Default - Dry-run validation, idempotency guarantees, rollback support
  • Full Observability - Structured events, audit trails, execution logs
  • Validated Operations - Schema validation, type checking, state verification
  • AI-Friendly Format - Simple YAML that any AI can generate and understand
  • Zero Dependencies - Single binary, no Python, no modules, no setup
  • Cross-Platform - Linux, macOS, Windows with unified interface
  • Dry-run Everything - Preview all changes before applying
  • Declarative - Describe desired state, not steps to get there

Comparison

Feature Mooncake Ansible Shell Scripts
Setup Single binary Python + modules Text editor
Dependencies None Python, modules System tools
AI Agent Friendly Native support Complex Unsafe
Dry-run Native Check mode Manual
Idempotency Guaranteed Yes Manual
Cross-platform Built-in Limited OS-specific
Best For AI agents, dotfiles Enterprise automation Quick tasks

Documentation

Full Documentation - Complete guide with examples

Quick links:

Local Examples

Try the examples in the examples/ directory:

# Clone and try
git clone https://github.com/alehatsman/mooncake.git
cd mooncake

# Run Hello World
mooncake run --config examples/01-hello-world/config.yml

# Browse all examples
ls examples/

Common Use Cases

Dotfiles Management

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

Development Environment Setup

- vars:
    packages: [neovim, ripgrep, fzf, tmux]

- name: Install dev tools
  shell: brew install {{item}}
  with_items: "{{packages}}"
  when: os == "darwin"

Multi-OS Configuration

- name: Install on Linux
  shell: apt install neovim
  become: true
  when: os == "linux"

- name: Install on macOS
  shell: brew install neovim
  when: os == "darwin"

Testing

Thoroughly tested across multiple platforms:

  • Linux: Ubuntu, Debian, Alpine, Fedora
  • macOS: Intel and Apple Silicon
  • Windows: Windows Server

See Testing Documentation for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT License - Copyright (c) 2026 Aleh Atsman

See LICENSE file for details.

Read the Full Documentation for detailed guides, examples, and reference materials.

Directories

Path Synopsis
Package main provides the mooncake CLI application.
 Package main provides the mooncake CLI application.
internal
actions
Package actions provides the action handler system for mooncake.
 Package actions provides the action handler system for mooncake.
actions/artifact_capture
Package artifact_capture implements the artifact.capture action handler.
 Package artifact_capture implements the artifact.capture action handler.
actions/artifact_validate
Package artifact_validate implements the artifact.validate action handler.
 Package artifact_validate implements the artifact.validate action handler.
actions/assert
Package assert implements the assert action handler.
 Package assert implements the assert action handler.
actions/command
Package command implements the command action handler.
 Package command implements the command action handler.
actions/copy
Package copy implements the copy action handler.
 Package copy implements the copy action handler.
actions/download
Package download implements the download action handler.
 Package download implements the download action handler.
actions/file
Package file implements the file action handler.
 Package file implements the file action handler.
actions/file_delete_range
Package file_delete_range implements the file_delete_range action handler.
 Package file_delete_range implements the file_delete_range action handler.
actions/file_insert
Package file_insert implements the file_insert action handler.
 Package file_insert implements the file_insert action handler.
actions/file_patch_apply
Package file_patch_apply implements the file_patch_apply action handler.
 Package file_patch_apply implements the file_patch_apply action handler.
actions/file_replace
Package file_replace implements the file_replace action handler.
 Package file_replace implements the file_replace action handler.
actions/include_vars
actions/package
Package package_handler implements the package action handler.
 Package package_handler implements the package action handler.
actions/preset
Package preset implements the preset action handler.
 Package preset implements the preset action handler.
actions/print
Package print implements the print action handler.
 Package print implements the print action handler.
actions/repo_apply_patchset
Package repo_apply_patchset implements the repo_apply_patchset action handler.
 Package repo_apply_patchset implements the repo_apply_patchset action handler.
actions/repo_search
Package repo_search implements the repo_search action handler.
 Package repo_search implements the repo_search action handler.
actions/repo_tree
Package repo_tree implements the repo_tree action handler.
 Package repo_tree implements the repo_tree action handler.
actions/service
Package service implements the service action handler.
 Package service implements the service action handler.
actions/shell
Package shell implements the shell action handler.
 Package shell implements the shell action handler.
actions/template
Package template implements the template action handler.
 Package template implements the template action handler.
actions/testutil
Package testutil provides shared testing utilities for action handlers.
 Package testutil provides shared testing utilities for action handlers.
actions/unarchive
Package unarchive implements the unarchive action handler.
 Package unarchive implements the unarchive action handler.
actions/vars
Package vars implements the vars action handler.
 Package vars implements the vars action handler.
actions/wait
Package wait implements the wait action handler.
 Package wait implements the wait action handler.
agent
Package agent provides autonomous agent functionality for iterative plan generation and execution.
 Package agent provides autonomous agent functionality for iterative plan generation and execution.
artifacts
Package artifacts provides enhanced metadata structures for artifact generation.
 Package artifacts provides enhanced metadata structures for artifact generation.
config
Package config provides data structures and validation for mooncake configuration files.
 Package config provides data structures and validation for mooncake configuration files.
docgen
Package docgen provides automated documentation generation from action metadata.
 Package docgen provides automated documentation generation from action metadata.
effects
Package effects provides the default implementation of actions.Performer — mode-aware filesystem and command primitives used by action handlers.
 Package effects provides the default implementation of actions.Performer — mode-aware filesystem and command primitives used by action handlers.
errors
Package errors provides error hint inference for structured step failure output.
 Package errors provides error hint inference for structured step failure output.
events
Package events provides the event system for Mooncake execution lifecycle.
 Package events provides the event system for Mooncake execution lifecycle.
executor
Package executor provides the execution engine for mooncake configuration steps.
 Package executor provides the execution engine for mooncake configuration steps.
explain
Package explain provides functionality for displaying system information in a human-readable format.
 Package explain provides functionality for displaying system information in a human-readable format.
expression
Package expression provides expression evaluation capabilities for conditional execution.
 Package expression provides expression evaluation capabilities for conditional execution.
facts
Package facts provides system information collection for different operating systems.
 Package facts provides system information collection for different operating systems.
filetree
Package filetree provides directory tree walking functionality for with_filetree operations.
 Package filetree provides directory tree walking functionality for with_filetree operations.
llm
Package llm provides LLM client implementations for plan generation.
 Package llm provides LLM client implementations for plan generation.
logger
Package logger provides logging interfaces and implementations for mooncake.
 Package logger provides logging interfaces and implementations for mooncake.
mcp
Package mcp implements a minimal MCP (Model Context Protocol) server over stdio transport using JSON-RPC 2.0.
 Package mcp implements a minimal MCP (Model Context Protocol) server over stdio transport using JSON-RPC 2.0.
pathutil
Package pathutil provides path expansion and validation utilities.
 Package pathutil provides path expansion and validation utilities.
plan
Package plan provides plan generation and persistence for mooncake configurations.
 Package plan provides plan generation and persistence for mooncake configurations.
presets
Package presets provides preset loading and expansion functionality.
 Package presets provides preset loading and expansion functionality.
register
Package register imports all action handler packages to trigger their init() functions.
 Package register imports all action handler packages to trigger their init() functions.
registry
Package registry provides preset distribution and caching functionality.
 Package registry provides preset distribution and caching functionality.
runlog
Package runlog persists a compact record of every mooncake run to ~/.mooncake/runs.jsonl and provides a reader for the most recent entry.
 Package runlog persists a compact record of every mooncake run to ~/.mooncake/runs.jsonl and provides a reader for the most recent entry.
schemagen
Package schemagen provides JSON Schema generation from action metadata.
 Package schemagen provides JSON Schema generation from action metadata.
security
Package security provides password input methods and redaction for sensitive data.
 Package security provides password input methods and redaction for sensitive data.
snapshot
Package snapshot provides repository snapshot functionality for agent context.
 Package snapshot provides repository snapshot functionality for agent context.
template
Package template — list resolution.
 Package template — list resolution.
utils
Package utils provides utility functions for file operations.
 Package utils provides utility functions for file operations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.