How to Install Moltbot on Mac

Mac is probably the smoothest platform for running Moltbot. I say "probably" because Linux people will fight me on that, but whatever. It works great on Mac and that's what matters here.

This guide covers everything from installing Node.js to getting the dashboard running. If you've already done the Getting Started guide and everything worked, you might not need this page. But stick around -- there's Mac-specific stuff here that the general guide doesn't cover.

Prerequisites

Node.js 22+

You need Node.js version 22 or newer. Check what you've got:

node --version

If you see v22.x.x or higher, skip ahead. If not, here's how to get it.

Option A: nvm (recommended)

If you don't have nvm yet:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Close and reopen your terminal. Then:

nvm install 22
nvm use 22
nvm alias default 22

That last line makes Node 22 your default so you don't have to nvm use every time you open a new terminal. I forgot this once and spent 20 minutes wondering why Moltbot stopped working after a reboot. Don't be me.

Option B: Homebrew

brew install node@22

Then make sure the Homebrew Node is in your PATH. Homebrew usually tells you how to do this after the install. Read the output -- people never read the output and then wonder why things don't work.

Option C: Download from nodejs.org

Go to nodejs.org, download the v22 LTS installer for macOS, run it. Simple. Old school.

Xcode Command Line Tools

You might need these for some npm packages that compile native addons:

xcode-select --install

If it says they're already installed, great. If it pops up a dialog, click Install and wait. It takes a few minutes.

Installing Moltbot

Straightforward:

npm install -g moltbot@latest

Verify:

moltbot --version

Should show v2026.1.24 or whatever the latest version is. If you get a permission error on the npm install -g command, DON'T use sudo. Fix your npm permissions instead. Using nvm avoids this problem entirely, which is another reason I recommend it.

Running the Onboarding

moltbot onboard --install-daemon

This does a few things on Mac specifically:

1. Creates your config directory at ~/.moltbot/
2. Walks you through the setup wizard (API keys, basic settings)
3. Installs a launchd service for the Moltbot daemon

That third point is the Mac-specific part. On Mac, background services are managed by launchd (Apple's version of systemd, sort of). The --install-daemon flag creates a launchd plist file so Moltbot starts automatically when you log in.

You can verify the service is loaded:

launchctl list | grep moltbot

If you see a line with "moltbot" in it, the daemon is registered. The first number is the PID (process ID) -- if it's a number, the daemon is running. If it's a dash -, it's registered but not currently running.

Starting the Dashboard

moltbot dashboard

Open http://127.0.0.1:18789/ in your browser. Safari, Chrome, Firefox, Arc, whatever. They all work.

You should see the Moltbot dashboard. Type a message, get a reply. That's the moment of truth.

The launchd Service (Important)

This part tripped me up when I first set things up, so let me explain it properly.

When you run moltbot onboard --install-daemon, it creates a launchd plist file. This is basically a config file that tells macOS "hey, run this program in the background and keep it running."

The daemon starts automatically when you log in. You don't need to manually start it every time.

Checking daemon status

moltbot doctor

This is the easiest way. It'll tell you if the daemon is running, and if not, why not.

You can also check directly:

launchctl list | grep moltbot

Restarting the daemon

If the daemon is acting weird:

launchctl stop com.moltbot.daemon
launchctl start com.moltbot.daemon

The exact service name might be slightly different -- check with launchctl list | grep moltbot to see the full identifier.

Removing the daemon

If you want to uninstall or reinstall the daemon:

launchctl unload ~/Library/LaunchAgents/com.moltbot.daemon.plist

Then run moltbot onboard --install-daemon again to reinstall it.

Apple Silicon vs Intel

Moltbot works on both Apple Silicon (M1, M2, M3, M4) and Intel Macs. Node.js 22 has native ARM support so there's no Rosetta weirdness to deal with.

One thing to watch out for: if you previously had Node.js installed under Rosetta (x86 emulation) and then switch to a native ARM version, your global npm packages might get confused. Cleanest fix: uninstall the old Node, install nvm fresh, and reinstall your global packages. Annoying but it only takes a few minutes.

Building from Source on Mac

If you want to build Moltbot from source instead of using the npm package:

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build
pnpm build

You need pnpm for this:

npm install -g pnpm

The build process is pretty quick on Apple Silicon. My M2 MacBook Air does a full build in about a minute. Intel Macs are a bit slower but nothing crazy.

Firewall and Network

Moltbot's gateway listens on 127.0.0.1 (loopback) by default. This means it's only accessible from your own machine. macOS's built-in firewall won't even notice it because loopback traffic doesn't go through the firewall.

You might see a macOS dialog asking "Do you want the application 'node' to accept incoming network connections?" -- this usually pops up the first time. You can click Allow. It's fine. The gateway is bound to loopback anyway so nothing is actually exposed to your network.

If you're running Moltbot on a Mac that's also a server (some people do this, especially with Mac Minis), and you want to access the dashboard from another machine, use an SSH tunnel:

ssh -L 18789:127.0.0.1:18789 your-mac-hostname

Then access http://127.0.0.1:18789/ from your local machine. The traffic goes through the SSH tunnel. Secure.

Or use Tailscale. Tailscale is honestly one of my favorite pieces of software. Zero-config VPN, works everywhere, free for personal use. If you're not using it already, give it a look.

Common Mac Issues

"Permission denied" on npm install -g

Don't use sudo. Fix npm permissions:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

Add export PATH=~/.npm-global/bin:$PATH to your ~/.zshrc (or ~/.bashrc if you're still on bash). Then run source ~/.zshrc and try the install again.

Or just use nvm. Seriously. It handles all of this.

Daemon doesn't start after reboot

Check if the plist file exists:

ls ~/Library/LaunchAgents/ | grep moltbot

If it's not there, run the onboarding again:

moltbot onboard --install-daemon

If it IS there but the daemon still doesn't start, check the launchd logs. They're usually in ~/Library/Logs/ or you can use Console.app to search for moltbot-related entries.

Port 18789 already in use

Something else is using that port. Find out what:

lsof -i :18789

Kill whatever it is, or configure Moltbot to use a different port in your config file.

"moltbot: command not found" after install

Your shell doesn't know where npm installed global packages. If you're using zsh (the default on modern macOS):

export PATH="$PATH:$(npm config get prefix)/bin"

Add that line to ~/.zshrc to make it permanent.

Everything else

moltbot doctor

Run it. Read what it says. It's genuinely helpful.

Tips for Mac Users

Use iTerm2 or Warp instead of the default Terminal.app. Not a Moltbot requirement -- just a quality of life thing. Terminal.app works fine, but iTerm2 and Warp are so much nicer.

Keep Node.js updated. New versions come out regularly and Moltbot tends to use newer Node features. With nvm, updating is just nvm install 22 (it gets the latest 22.x).

The dashboard works great in Arc if you're using that browser. You can pin it as a sidebar tab and it stays out of the way. I keep it open all day.

moltbot doctor is your friend. I know I keep saying this. But it's true. When something feels off, run it before you start debugging manually.

You're all set. Go use Moltbot.