Picoclaw: A mighty ultra-light agent

Picoclaw was inspired by the nanobot project — a small agent with functionality similar to the popular OpenClaw project. Picoclaw is an agent harness: it orchestrates an LLM within an infinite loop, and provides remote communication channels, tool use, skills, and long-term memory. This makes it far more powerful than a basic prompt-and-answer session.

Being security-conscious, I was not comfortable using OpenClaw in its current form. After some searching, I found Picoclaw, which is highly efficient since it was written in Go. Go programs compile to tight executables; the Picoclaw binary comes in at about 16MB, making it not only fast but scalable on inexpensive hardware. After an initial security audit, I decided the safest way to enter the agent world was to fork Picoclaw into my own repo, picoclaw-armored, and refine it as a security-first agent.

I made multiple passes through the code, addressing 15 security issues. One of them was an embedded API key for a Google service. I removed all communication channels except WhatsApp and Discord. (I had originally removed Discord as well, but added it back since bots connected to Discord don't require a phone number.) I also hardened the agent definition files: AGENTS.md, IDENTITY.md, and SOUL.md. If you are setting up an agent for the first time, you can customize USER.md to taste. Hardware support for the MaixCam was commented out. For a full list of changes, see the pull requests in the repo. I feel a little selfish not submitting PRs upstream for the security fixes, but I needed to move quickly to get things off the ground — I may circle back to that later.

Once I had a secure version (afaik), I tested it first in a Fedora Linux virtual machine. I installed from source and compiled a local binary. I used Google's Gemini Flash Lite as the LLM. I created a dedicated Google Cloud project and API key for my agents. The model and API key are both set in the main configuration file: config.json. If you are running a single local agent, the default configuration and workspace files live in \(HOME/.picoclaw. However, since I wanted to run more than one agent, I set each up in \)HOME/picoclaw-armored-agents/ and passed the config file location and workspace directory as environment variables. Here is what the startup command looks like for my chief of staff agent:

PICOCLAW_HOME=/path/to/picoclaw-armored-agents/chief \
PICOCLAW_CONFIG=/path/to/picoclaw-armored-agents/chief/config.json \
picoclaw gateway

Each agent can be started with its own home directory and config file. Note that remote communications default to port 18790, as set in the config file. For a second agent, the port needs to be changed to a unique value (e.g., 18791, and 18792 for a third, and so on). Keep in mind that a single agent is already capable of spawning and managing sub-agents, so you may not need more than one. Running multiple distinct agents was primarily a learning exercise for me, though I do plan to customize each one rather than running a single general-purpose instance.

I initially tried setting up WhatsApp for communications. I wanted each agent to have its own phone number and provisioned one through Google Voice — but WhatsApp refused to authenticate it because it was a VoIP number rather than a real mobile number. I turned to Discord instead. It took some trial and error to configure a bot correctly for my use case since I had no prior experience with Discord bots. The Picoclaw documentation covers the critical options.

Here is a complete step-by-step guide to connecting a picoclaw-armored agent to a Discord bot.

Step 1: Set Up Your Discord Server

Create a Discord server (e.g., "Agent HQ").
Recommended: Create a private text channel for the agent and restrict access to it.

Step 2: Create the Bot in the Developer Portal

Go to the Discord Developer Portal.
Click New Application and give it a name.
On the Installation tab, uncheck Guild Install to keep the bot private.
Navigate to the Bot tab and configure the following:
- Uncheck Public Bot (security hardening).
- Enable the Message Content Intent so the bot can receive messages.
- Grant Administrator permissions.
- Click Reset Token and copy the token — you will need this for config.json.

Step 3: Generate an Invite Link

In the Developer Portal, select your application.
Go to OAuth2 → URL Generator.
Under Scopes, check bot (and applications.commands if using slash commands).
Under Bot Permissions, select the required permissions (e.g., Send Messages, Read Message History).
Copy the generated URL at the bottom of the page.

Step 4: Add the Bot to Your Server

Paste the invite URL into a browser.
Select your server from the dropdown.
Click Continue, review the permissions, then click Authorize.
Complete the CAPTCHA if prompted.

The bot will now appear in your server's member list with an offline status. It will come online once the picoclaw gateway process is running with its token.

Step 5: Restrict the Bot to Your User ID

To prevent unauthorized users from consuming your API tokens:

Enable Developer Mode in Discord: Settings → Advanced → Developer Mode.
Right-click your profile picture in any chat and select Copy User ID.
Add an allow_from field to the discord section of your config.json:

"discord": {
  "enabled": true,
  "allow_from": "YOUR_DISCORD_USER_ID",
  "token": "YOUR_BOT_TOKEN_HERE"
}

Step 6: Start the Picoclaw Gateway

Run the picoclaw gateway process with the bot token in place. Once running, the bot's status will change from offline to online in your server.

After getting a couple of agents running, I tried deploying picoclaw-armored on a five-year-old Raspberry Pi 3 I had in a closet. Because the software repositories were no longer supported, I had to download and manually install Go. After that, it compiled and ran just as responsively — from the Discord side — as the instance on my main computer. It was a great proof-of-concept exercise. I briefly considered setting up a cluster of Raspberry Pis, each running its own agent, but concluded it would be easier to manage and extend on a single, more capable (but still inexpensive) machine. The next step is to explore skills.