PicoClaw on Mac: Installation and Setup

PicoClaw is a small, single-binary AI assistant written in Go. This guide covers PicoClaw on Mac from install to an always-running gateway, with Apple silicon in mind.

What PicoClaw is

PicoClaw is an open-source personal AI assistant from Sipeed, released under the MIT licence. It is built to run on very low-cost hardware: the project describes it as a single binary across RISC-V, ARM, MIPS and x86, with a memory footprint of around 10–20MB in recent builds. It connects to 30+ LLM providers through a model_list in its config, including OpenAI, Anthropic, Google Gemini, OpenRouter, DeepSeek and Groq, plus local servers such as Ollama and vLLM.

You talk to it in the terminal or through chat channels. The README lists Telegram, Discord, WhatsApp, Slack, Matrix, Feishu / Lark, DingTalk, WeCom, QQ, Weixin, LINE and more. It also has a cron tool for reminders and recurring tasks.

Two things to know before you start. First, the project itself warns: do not deploy to production before v1.0. Second, PicoClaw is a third-party project; Hatmac is not affiliated with Sipeed.

Why run it on a Mac

PicoClaw does not need a big machine. The reason to run it on a Mac is what sits next to it: a local model server such as Ollama, your macOS tools, and a machine that stays on. A Mac mini can host the assistant and a local model together, which keeps prompts on hardware you control. For the wider picture, see AI agents on Mac mini.

Install PicoClaw on Mac

Option 1: Homebrew

PicoClaw is available as a formula in Homebrew core, with bottles for Apple silicon:

brew install picoclaw
which picoclaw

This is the simplest route on a remote Mac, and it gives you a service you can manage with brew services, covered below.

Option 2: Release archive

Each GitHub release includes picoclaw_Darwin_arm64.tar.gz for Apple silicon. Download it from the Releases page, then:

tar -xzf picoclaw_Darwin_arm64.tar.gz
./picoclaw onboard

The macOS package also contains picoclaw-launcher, a web UI. Because it is not notarised, macOS may block it the first time. Open System Settings, go to Privacy & Security, click Open Anyway in the Security section and confirm. You only need to do this once.

Option 3: Build from source

Building needs Go 1.25 or later, plus Node.js 22+ and pnpm for the web UI. Follow the build section of the README; make build and make install are the main targets.

Onboarding and configuration

Run onboarding once. It creates ~/.picoclaw/config.json and a workspace directory:

picoclaw onboard

The config holds non-sensitive settings. Models are defined in model_list, and agents.defaults.model_name picks the default. API keys are not stored in config.json: PicoClaw keeps them in a separate .security.yml file. If you edit secrets by hand, follow docs/security/security_configuration.md in the repo.

Here is the shape of a config that uses a local Ollama model, based on the README's example:

{
  "agents": { "defaults": { "model_name": "local-llama" } },
  "model_list": [
    {
      "model_name": "local-llama",
      "model": "ollama/llama3.1:8b",
      "api_base": "http://localhost:11434/v1"
    }
  ]
}

The schema is versioned and migrates automatically, so edit the file onboarding wrote rather than pasting a full config over it. Local providers such as Ollama do not need an API key. To set up Ollama itself on an always-on Mac, see Ollama on a Mac mini server.

Test the model before you add channels:

picoclaw agent -m "Say hello in one sentence."
picoclaw agent
picoclaw status

The gateway and the launcher

Chat channels and webhooks go through the gateway:

picoclaw gateway

It listens on 127.0.0.1:18790 by default, set by gateway.host and gateway.port. Only one picoclaw gateway instance should run at a time.

If you prefer a browser, picoclaw-launcher starts a web UI at http://localhost:18800. The quick start there is: configure a provider, configure a channel such as Telegram, start the gateway, then chat. Note that picoclaw-launcher-tui is being phased out; use picoclaw-launcher.

Run PicoClaw persistently

An assistant that only runs while your terminal is open is not much use. On a Mac there are two documented ways to keep it running.

Homebrew service

brew services start picoclaw
brew services info picoclaw
brew services restart picoclaw

This registers a launchd service that starts now and again at login. Because it is tied to your user login, make sure the user session comes back after a reboot, either by logging in through remote desktop or with automatic login if your security setup allows it.

Docker Compose

If Docker is installed on the Mac, the repo ships a Compose file:

docker compose -f docker/docker-compose.yml --profile launcher up -d
docker compose -f docker/docker-compose.yml pull

On first run, it writes docker/data/config.json for you to edit.

Keep the Mac awake

Either way, a sleeping Mac stops answering. Turn off system sleep:

sudo pmset -a sleep 0
pmset -g

Scheduled jobs created with the cron tool are stored in ~/.picoclaw/workspace/cron/ and only run while PicoClaw is running, which is another reason to keep it up.

Security on a remote Mac

• Keep the defaults. The gateway listens on 127.0.0.1. Do not change gateway.host to a public address.
• Tunnel the web UI. To use the launcher on a cloud Mac, forward the port over SSH instead of opening it: ssh -N -L 18800:127.0.0.1:18800 you@your-mac, then open http://localhost:18800 on your laptop.
• Protect keys. Keep API keys in .security.yml, not in config.json or shell scripts, and do not commit either file.
• Limit who can talk to it. Configure each channel so only your accounts can message the bot, and review the tools you enable, such as web access and MCP servers.
• Treat it as pre-1.0. Pin a version, read the release notes before updating, and keep it away from production systems until the project reaches v1.0.

For connecting to the Mac itself, see how to access a remote Mac.

Which Mac to use

PicoClaw alone barely uses memory. Size the Mac for the model. With a hosted API, a Mac mini M4 with 16GB is plenty. With a local Ollama model, use the rule of thumb: roughly 7–8B models on 16GB and up to about 14B on 24GB, depending on context length. If you want a heavier agent with more tools, compare it with running OpenClaw on a Mac mini 24/7.

Prices in USD per month for each machine's starting configuration. More memory, storage or several machines? Ask us.

FAQ

Does PicoClaw run natively on Apple silicon Macs?

Yes. The releases include a Darwin arm64 archive, and the Homebrew formula has Apple silicon bottles.

Where does PicoClaw on Mac keep its config?

In ~/.picoclaw/config.json, created by picoclaw onboard. API keys go in a separate .security.yml.

Can PicoClaw use a local model instead of a cloud API?

Yes. Add an Ollama or vLLM entry to model_list with its api_base. Local providers do not need an API key.

Need a Mac that stays on for your assistant? See plans, or tell us what you need.