Setting Up Moltbot on a Mac Mini

Why a Mac Mini?

A Mac mini makes an excellent always-on home for your AI assistant:

• ⚡ Always available — No laptop to close, no desktop to shut down
• 🔋 Low power — M-series chips sip electricity
• 🖥️ Headless friendly — Runs fine without a display
• 🚀 Native performance — No VMs or containers needed
• 🍎 Integration — Native access to Calendar, Reminders, Notes, and more

This guide assumes you have a Mac mini (M1 or later recommended) running macOS Sonoma or newer, connected to your home network.

Prerequisites

Before starting, you'll need:

• 🔑 Claude access — Either a Claude Max subscription or an Anthropic API key (see below)
• 🔒 Tailscale (recommended) — For secure remote access without exposing ports

Claude Max vs API Key

You have two options for connecting to Claude:

Recommendation: If you already have Claude Max, start there — no extra cost. If you're a heavy user or want more control, the API gives you flexibility.

Step 1: Install Moltbot

Run the quickstart installer:

This handles everything: installs Node.js if needed, installs Moltbot globally, and sets up your PATH. On macOS, it uses Homebrew for Node; on Linux, it uses NodeSource.

Verify the installation:

Step 2: Initial Setup

Run the setup wizard:

This will create your config directory at ~/.clawdbot and generate a gateway token. Save the token somewhere secure — you'll need it to access the Control UI.

Option A: Claude Max (OAuth)

If you have a Claude Max subscription, authenticate with your Claude account:

This opens a browser window to sign in with your Claude account. Once authenticated, Moltbot uses your subscription — no API key needed.

Option B: Anthropic API Key

If you're using the API, add your key to the config:

{
  anthropic: {
    apiKey: "sk-ant-..."
  }
}

Or set it as an environment variable: export ANTHROPIC_API_KEY="sk-ant-..."

Step 3: Lock Down File Permissions

Before adding any sensitive configuration, secure the directory:

This ensures only your user account can read the config, credentials, and session transcripts.

Step 4: Configure the Gateway

Edit your config to bind the gateway to localhost only:

Add or update the gateway section:

{
  gateway: {
    bind: "loopback",
    controlUi: {
      allowInsecureAuth: false
    }
  }
}

This prevents the gateway from being accessible on your local network — we'll set up secure remote access next.

Step 5: Set Up Tailscale Serve

Tailscale Serve lets you access your Moltbot securely from anywhere on your tailnet with automatic HTTPS.

First, make sure Tailscale is installed and connected:

brew install tailscale
# Then open Tailscale from Applications and sign in

Enable HTTPS certificates in your Tailscale admin console under DNS settings.

Start Tailscale Serve:

You'll get a URL like https://your-mac-mini.tailnet-name.ts.net/ that works from any device on your tailnet — phone, laptop, anywhere.

Step 6: Add a Messaging Channel

Moltbot supports multiple channels. Here's how to set up Telegram with security best practices:

Create a Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token you receive

Configure with Allowlist

Instead of the default "pairing" mode, lock it down to just your Telegram user ID:

{
  channels: {
    telegram: {
      token: "YOUR_BOT_TOKEN",
      dmPolicy: "allowlist",
      allowFrom: ["YOUR_TELEGRAM_USER_ID"]
    }
  }
}

Finding your Telegram user ID: Message @userinfobot, or send a message to your bot and check clawdbot logs --follow for from.id.

Step 7: Set Up Your Workspace

Create a workspace directory for your assistant:

mkdir -p ~/moltbot
cd ~/moltbot

Create the essential files:

# AGENTS.md

This is your workspace. Read SOUL.md to know who you are.
Read memory files to remember what happened.
Write things down — you wake up fresh each session.

# SOUL.md

Be helpful, be direct, skip the filler.
Have opinions. Be resourceful before asking.
Private things stay private.

# USER.md

Name: [Your name]
Timezone: America/Los_Angeles
Notes: [Anything your assistant should know]

Point Moltbot at this workspace:

{
  agents: {
    defaults: {
      workspace: "~/moltbot"
    }
  }
}

Step 8: Start the Gateway

Start Moltbot as a background service:

Check that it's running:

To have it start automatically on boot:

Step 9: Run a Security Audit

Before going further, verify your setup:

Address any warnings. For a deeper check:

Step 10: Test It Out

1. Telegram: Message your bot and verify it responds (and only to you)
2. Control UI: Visit your Tailscale Serve URL and sign in with your gateway token
3. Web Chat: Use the Control UI's chat interface for a quick test

Optional: Deeper Hardening

For additional security, see Locking Down Your Moltbot. Quick wins:

Enable Exec Approvals

Require your approval before shell commands run. Configure via ~/.clawdbot/exec-approvals.json:

{
  "defaults": {
    "security": "allowlist",
    "ask": "on-miss",
    "askFallback": "deny"
  }
}

Enable Sandboxing

Run commands in an isolated Docker container:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
        workspaceAccess: "rw"
      }
    }
  }
}

Restrict Tools

Deny access to dangerous tools:

{
  agents: {
    defaults: {
      tools: {
        deny: ["exec", "browser", "gateway"]
      }
    }
  }
}

Maintenance

Troubleshooting

Bot not responding?

• → Check clawdbot status to ensure the gateway is running
• → Check clawdbot logs for errors
• → Verify your Telegram bot token is correct

Can't access Control UI remotely?

• → Ensure Tailscale Serve is running: tailscale serve status
• → Check that HTTPS certificates are enabled in Tailscale admin
• → Verify you're on the same tailnet

Permission errors?

• → Run clawdbot security audit to check file permissions
• → Ensure ~/.clawdbot is owned by your user

What's Next?

Your Moltbot is now running securely on dedicated hardware. From here you can:

• 💬 Add more channels — WhatsApp, Discord, Slack, iMessage
• 🧩 Install skills — Browse clawdhub.com for capabilities
• 💓 Set up heartbeats — Periodic check-ins for email, calendar, etc.
• 🔗 Connect services — Google Workspace, 1Password, GitHub, and more

For the full security guide, see Locking Down Your Moltbot. 🔐

Resources

• → Moltbot - Personal AI assistant
• → Moltbot Docs - Full documentation
• → Moltbot Discord - Community support
• → Tailscale Serve - Secure HTTPS tunneling