Installation

Follow these steps to install Desktop Homunculus and set up your MOD environment.

System Requirements

	macOS
OS	macOS 12 (Monterey) or later
CPU	Apple Silicon or Intel
Node.js	22 or later
Disk Space	500 MB or more

Windows Support

Windows support is planned. Currently, only macOS is supported.

Step 1: Install Desktop Homunculus

Download the latest release from the GitHub Releases page.

1. Download the .dmg file
2. Open the DMG and drag Desktop Homunculus into your /Applications folder
3. Launch the app from Applications

Gatekeeper Warning

If macOS shows "Desktop Homunculus can't be opened because it is from an unidentified developer":

1. Open System Settings > Privacy & Security
2. Scroll down and click Open Anyway
3. Click Open in the confirmation dialog

Step 2: Install Node.js

Desktop Homunculus MODs require Node.js 22 or later to run TypeScript scripts directly using tsx.

1. Visit the Node.js download page
2. Download and install the LTS version (22 or later)
3. Verify the installation:

node -v

The output should show v22.0.0 or higher.

tip

If you already have Node.js installed, check the version with node -v. If it's below v22, update to the latest LTS version.

Step 3: Install MOD Management Tools

Install pnpm (package manager) and @hmcs/cli (MOD management CLI) globally:

npm install -g pnpm @hmcs/cli

Platform Support

The hmcs CLI is currently supported on macOS only. Windows support is planned for a future release.

Verify the installation:

pnpm -v
hmcs --version

Permission Error

If you see EACCES permission errors, see the npm docs on resolving permission errors.

Step 4: Install Official MODs

Install the recommended set of official MODs:

hmcs mod install @hmcs/assets @hmcs/elmer @hmcs/menu @hmcs/character-settings @hmcs/settings

MOD	Description
@hmcs/assets	Default animations and sound effects
@hmcs/elmer	Default character model
@hmcs/menu	Right-click context menu
@hmcs/character-settings	Per-character settings panel
@hmcs/settings	Application settings (frame rate, shadow opacity) via system tray

Step 5: Verify Installation

1. Launch Desktop Homunculus
2. A character should appear on your desktop
3. Right-click the character to open the context menu

If everything works, you're all set!

Next Steps

Head over to the Quick Start guide to learn how to interact with your character.

Troubleshooting

hmcs: command not found

Your terminal doesn't recognize the hmcs command.

• Restart your terminal — the PATH may not have been updated
• Verify the global npm bin directory is in your PATH:

  npm bin -g

Node.js version is below 22

MODs require Node.js 22+ to run TypeScript scripts directly via tsx. Download the latest LTS from nodejs.org.

App blocked by Gatekeeper

See Step 1 for instructions on allowing the app.

No character appears after installing MODs

Restart Desktop Homunculus. MOD changes take effect after a restart.

MOD installation fails

Check your network connection and try again.