Moltbot Setup Guide: Zero to First Reply

Alright, let's actually get this thing running. No theory, no philosophy, just commands and clicks until you see your first agent reply.

I'm going to assume you've already read the What is Moltbot? page and you know roughly what you're getting into. If not, go read that first. I'll wait.

Done? Cool.

Before You Start

You need Node.js 22 or newer. This is non-negotiable. Moltbot won't even start on older versions.

Check your version:

node --version

If you see something like v22.4.0 or higher, you're good. If it says v18.something or v20.something, you need to upgrade. I recommend using nvm to manage Node.js versions because juggling global Node installs is a nightmare.

nvm install 22
nvm use 22

If you don't have nvm... honestly just go install it. It's like 30 seconds and it'll save you so much pain later.

Platform Check

• Mac: You're good to go. No special requirements.
• Linux: You're good to go.
• Windows: You need WSL2. Not WSL1, not Git Bash, not Cygwin. WSL2. Native Windows is not supported at all. Check the Windows setup guide for the full walkthrough.

Step 1: Install Moltbot

Open your terminal and run:

npm install -g moltbot@latest

This installs the moltbot CLI globally. Takes maybe 30 seconds depending on your internet.

Verify it worked:

moltbot --version

You should see something like v2026.1.24 (or whatever the latest version is when you're reading this). If you get "command not found," your npm global bin directory probably isn't in your PATH. That's a whole other rabbit hole -- google "npm global packages not found" for your OS.

Step 2: Run the Onboarding

This is the part that actually sets everything up:

moltbot onboard --install-daemon

What does this do? A few things:

1. Creates the config directory (usually ~/.moltbot/)
2. Walks you through basic configuration -- API keys, default agent settings, that kind of stuff
3. Installs the daemon as a background service

On Mac, the daemon gets registered as a launchd service. On Linux, it depends on your init system. The point is: after this command, Moltbot runs in the background automatically. Even after reboots. Neat.

The onboarding wizard asks you some questions. Don't stress about getting everything perfect -- you can change all of this later through the dashboard or config files.

Step 3: Open the Dashboard

Now the fun part:

moltbot dashboard

This starts the web dashboard. Open your browser and go to:

http://127.0.0.1:18789/

You should see the Moltbot dashboard UI. If you see a connection error, the daemon might not be running yet. Give it a few seconds, or check:

moltbot doctor

This diagnostic command will tell you exactly what's wrong. Maybe the daemon didn't start. Maybe a port is already in use. Maybe your Node version is too old after all. moltbot doctor catches most of these issues.

Step 4: Get Your First Reply

In the dashboard, you should see a chat interface. Type something. Anything.

Hey, what can you do?

Hit enter.

If everything is wired up correctly, an agent will respond. That's it. You just got your first reply from a locally-running AI agent. Took you what, five minutes?

If you DON'T get a reply, or you get an error:

1. Check that your API key is configured correctly
2. Run moltbot doctor again
3. Check the logs in your ~/.moltbot/ directory
4. Make sure the daemon is actually running

Most first-time issues are API key problems. The onboarding wizard should have asked you for one, but sometimes people skip through it too fast. I've done it. Twice.

Step 5: Try Something Real

Chatting is nice, but the whole point of Moltbot is that agents can actually do things on your machine. Try asking it to:

List all the files in my home directory

or

What's the current time and date on this machine?

The agent should execute a command and show you the results. This is where Moltbot stops being a chatbot and starts being an agent. It's interacting with your system.

If you're nervous about that, good. You should be a little cautious. The sandbox settings in your config control what agents can and can't do. More on that in the advanced docs.

Installing from Source

Most people should just use the npm install. But if you want to hack on Moltbot itself, or you want the absolute latest code before it hits npm, you can build from source.

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

You need pnpm for this, not npm. If you don't have pnpm:

npm install -g pnpm

The pnpm ui:build step builds the dashboard frontend. The pnpm build step compiles everything else. The whole process takes a minute or two depending on your machine.

After building, you can run the CLI directly from the repo instead of the global install. Check the repo's README for details on that.

VPS Quick Install

Want to run Moltbot on a remote server? There's a one-liner:

curl -fsSL https://clawd.bot/install.sh | bash

Yes, piping curl to bash. I know some people hate this. Read the script first if you want -- it's open source.

For a VPS setup, you'll want at minimum 1 vCPU and 1GB RAM. The gateway listens on loopback by default (127.0.0.1), so it's not exposed to the internet. To access the dashboard remotely, use an SSH tunnel or Tailscale. Don't just open port 18789 to the world. Please.

A common VPS setup pattern:

adduser clawd && usermod -aG sudo clawd && su - clawd

This creates a dedicated user for running Moltbot. Don't run it as root. Just don't.

Then install Moltbot under that user account using the curl script or the npm method.

What You Should Do Next

You've got Moltbot running. You got a reply. Here's what I'd suggest:

1. Explore the dashboard -- poke around the settings, see what's there
2. Read your platform-specific guide -- Mac, Windows, or Docker for tips specific to your setup
3. Check moltbot doctor -- even if everything seems fine, it sometimes catches things you didn't notice
4. Try different prompts -- ask the agent to do increasingly complex things and see where the boundaries are

Don't try to learn everything at once. Get comfortable with the basics first. The advanced stuff -- custom agents, sandbox configs, multi-agent workflows -- that can wait.

Common Problems

"command not found" after install

Your npm global bin directory isn't in your PATH. On Mac/Linux:

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

Add that to your .bashrc or .zshrc to make it permanent.

Dashboard shows "connection refused"

The daemon isn't running. Try:

moltbot onboard --install-daemon

Or check moltbot doctor for more specific info.

Agent doesn't respond

Usually an API key issue. Check your config in ~/.moltbot/ and make sure the key is valid and has credits/quota.

Node.js version too old

node --version

Needs to be 22+. Use nvm to upgrade without breaking your other projects.

Everything else

moltbot doctor

Seriously, just run it. It catches like 90% of issues. That's what it's there for.

You're Up and Running

That wasn't so bad, right? You've got Moltbot installed, the daemon running, the dashboard open, and an agent that talks back to you. Everything from here is just refinement -- tweaking settings, learning what agents can do, figuring out your workflow.

Go build something cool.