[Support] NanoClaw — Lightweight Secure AI Agent for Unraid

NanoClaw is a lightweight, open-source personal AI agent that runs securely on your own server. It connects to Matrix and Telegram (via skill) and runs every agent session inside its own isolated Docker container — so the AI only sees what you explicitly give it access to.

Built as a minimal alternative to OpenClaw/Clawdbot, NanoClaw has ~15 source files you can actually read and understand. No complex config files — customise by telling Claude Code what you want changed.

Features

• Matrix (E2EE) channel support — Telegram available via skill install; WhatsApp, Slack, Discord in development

• Per-conversation isolated Docker containers — true OS-level sandbox, not application-level permissions

• Scheduled tasks — morning briefings, weekly reviews, automated reports

• Web search and fetch built in

• Agent Swarms — spin up teams of specialised agents that collaborate

• Per-group memory via CLAUDE.md files

• Anthropic API key authentication (console.anthropic.com)

Requirements

• Anthropic API key from console.anthropic.com — or a local model via per-group provider override (NANOCLAW_PROVIDER_BASE_URL + NANOCLAW_PROVIDER_API_KEY + NANOCLAW_PROVIDER_MODEL). Note: Claude Code OAuth tokens are no longer supported for automated/non-interactive use — CLAUDE_CODE_OAUTH_TOKEN will not produce a working agent.

• Matrix: Homeserver URL, bot user ID, and access token for a dedicated bot account

• Telegram: Bot token from @BotFather (optional — requires skill install, see NanoClaw changelog)

• At least one channel (Matrix or Telegram) must be configured

• Docker socket access (required — NanoClaw spawns isolated agent containers for each conversation)

Installation

Install via Community Applications and search for NanoClaw, or drop the template XML directly into /boot/config/plugins/dockerMan/templates-user/ on your Unraid server.

Required fields:

• HOST_PROJECT_ROOT — must match the host path of your AppData volume. The template defaults to /mnt/cache/appdata/nanoclaw but this must reflect where Unraid has actually placed the appdata on your system. If your cache pool or appdata share is configured differently, it may be /mnt/user/appdata/nanoclaw or another path. Verify with ls /mnt/cache/appdata/nanoclaw — if that returns nothing, adjust accordingly. A path mismatch here will cause agent containers to silently fail to spawn.

• ANTHROPIC_API_KEY — required, from console.anthropic.com

Telegram (optional, via skill):

• TELEGRAM_BOT_TOKEN from @BotFather

Matrix (optional):

• MATRIX_HOMESERVER_URL, MATRIX_BOT_USER_ID, MATRIX_ACCESS_TOKEN

• MATRIX_BOT_PASSWORD — k2's Matrix account password, used once on first startup to bootstrap cross-signing keys (eliminates the "unverified device" warning in Element X). After the first successful start, the bootstrap is skipped automatically — safe to leave set or remove.

Recommended:

• NANOCLAW_DOCKER_NETWORK — set to your Docker network name (e.g. ai-local) if you run Ollama, LiteLLM, or Paperclip on the same server. Without this, agent containers use the default bridge network and cannot reach those services by hostname.

At least one channel (Matrix or Telegram) must be configured.

After starting the container:

Matrix:

• Invite your bot account to a room

• The room auto-registers on first message

• Send @Andy hello — Andy will respond

Telegram (after skill install):

• Send /chatid to your bot

• The bot will reply with your chat ID and automatically register

• Send @Andy hello — Andy will respond

The trigger word is @Andy by default (configurable via NANOCLAW_TRIGGER).

To customise NanoClaw (change trigger word, add scheduled tasks, connect integrations), clone the repo and run claude in the project directory — Claude Code handles all configuration changes conversationally.

Links

• Template repository: https://github.com/bitcryptic-gw/unraid-nanoclaw

• Add to CA directly: https://raw.githubusercontent.com/bitcryptic-gw/unraid-nanoclaw/main/NanoClaw.xml

• NanoClaw project: https://github.com/qwibitai/nanoclaw

• Docker Hub image: https://hub.docker.com/r/bitcryptic/nanoclaw

Notes

The Docker socket mount (/var/run/docker.sock) is required — NanoClaw uses it to spawn isolated agent containers for each conversation. This is the same pattern used by Portainer, Watchtower, and similar tools.

Port 3001 is the internal credential proxy used by agent containers. It only needs to be accessible on the local Docker bridge network — you do not need to expose it externally.

NanoClaw stores its data in four directories under AppData: data/, store/, groups/, and logs/.

Post any issues or questions here and I'll do my best to help.

---

Changelog

v1.3.0 (2026-04-20)

• OneCLI credential support — NanoClaw now supports OneCLI as the core credential gateway for agent containers, aligned with upstream's architecture. Two new optional template variables: ONECLI_URL and ONECLI_API_KEY. Leave blank if you prefer the self-hosted native credential proxy (install the use-native-credential-proxy skill instead)

• Telegram removed from core — Telegram channel code has moved to the upstream qwibitai/nanoclaw-telegram skill repo, consistent with upstream's channel extraction architecture. Telegram remains fully functional via skill install; the bot token variable is retained in the template for compatibility

• New MCP skills — Vikunja task management skill added (VIKUNJA_URL, VIKUNJA_TOKEN). UnraidClaw, Tailscale, and Home Assistant skills stabilised and skill-files-only (env forwarding via template variables)

• Trigger matching tightened — trigger word must now appear at the start of a message (^@trigger) rather than anywhere in the message body

• Writable global memory mount — main agent now has write access to /workspace/global, fixing silent failures when Andy attempts to write global memory notes

v1.2.55 (2026-04-10)

• Telegram is now optional — Matrix-only setups no longer require a Telegram bot token

• Fixed MCP skill credentials (Ollama, Home Assistant, Tailscale, UnraidClaw) not reaching agent containers — all integrations now work correctly out of the box

• New variable: NANOCLAW_DOCKER_NETWORK — set to your Docker network name (e.g. ai-local) to allow agent containers to reach Ollama, LiteLLM, and Paperclip by hostname. Defaults to ai-local in the template

• New variable: MATRIX_BOT_PASSWORD — used once at startup to bootstrap Matrix cross-signing keys, eliminating the "unverified device" warning in Element/Element X. Safe to leave set; bootstrap is skipped automatically after the first run

• Matrix room cleanup: NanoClaw no longer auto-joins unregistered rooms on startup

v1.2.49 (2026-04-08)

• Matrix channel support with full E2EE (Rust crypto store, SQLite persistence across restarts)

• Telegram channel restored and stabilised

• ANTHROPIC_API_KEY now automatically injected into new group sessions — fresh installs no longer require manual file editing

• Matrix channel vars added to Unraid CA template

v1.2.25 (2026-03-16)

• /chatid command now auto-registers the chat — no manual SQLite setup required

• Fresh installs work out of the box — no need to copy .claude.json from another machine

• Stale sessions cleared automatically on container restart/update

• Fixed agent container file ownership issues that caused silent failures

• Docker socket mount corrected from Device to Path type (fixes Unraid compatibility)

• Multi-arch image (amd64 + arm64) on Docker Hub

Edited May 13May 13 by BitCryptic
Clarifications around deprecated OAUTH support, covering the option of local model use ie Ollama or similar

Interesting! What i wonder, how would you keep this updated? Is this a once run and forget here? Does changing nanoclaws code work?

On 3/20/2026 at 9:19 AM, martinjuhasz said:

Interesting! What i wonder, how would you keep this updated? Is this a once run and forget here? Does changing nanoclaws code work?

I don't follow your questions, sorry. Do you mean that I have the template pointed at my repo? I monitor the upstream and do periodic sync's to the latest stable builds. You can always switch the repo and point to the upstream directly or another if you wish. I'm not sure what you mean by 'run once and forget' ? NanoClaw is an open source project, anyone can contribute fixes or features (skills). I have a few that I've submitted.

Hello. What is the recommended method to just use telegram and bypass matrix all together?

3 hours ago, nathan9214 said:

Hello. What is the recommended method to just use telegram and bypass matrix all together?

I did get it working but with a lot of tweaking. I am curious if there is a better workflow. Hopefully one more repeatable.

Hi BitCryptic, thanks for the project and the template work.

I've hit a wall getting NanoClaw responding on Matrix and have done a fair bit of diagnostic work. Hoping you can spot what's wrong — happy to provide anything else useful.

Setup

• NanoClaw v1.3.0 (image: bitcryptic/nanoclaw:latest, container ID 4fd55fe1a417)

• Installed via Community Apps on Unraid

• Matrix-only (no Telegram configured)

• Auth via CLAUDE_CODE_OAUTH_TOKEN (no ANTHROPIC_API_KEY set)

• NANOCLAW_DOCKER_NETWORK=ai-local (network exists and is reachable)

• AppData at /mnt/cache/appdata/nanoclaw/

• Default trigger @Andy, bot user @nectaron-andy:matrix.org, homeserver matrix.org

What works

• Container starts cleanly, no errors

• Matrix invites auto-accept

• Crypto store bootstraps, cross-signing keys imported, device verifies, key backup activates

• Incoming messages decrypt successfully — logs show Decrypted event received with the correct room ID and event ID

• chats table in messages.db populates with each new room

What doesn't work

After Decrypted event received, nothing happens. No registration, no trigger evaluation, no agent spawn, no error. Just sync polling resumes.

• registered_groups table is empty across all attempts

• messages table is empty — incoming messages are never persisted

• /mnt/cache/appdata/nanoclaw/logs/ is empty

• /mnt/cache/appdata/nanoclaw/groups/ is empty

• docker ps -a shows only the main NanoClaw container — no agent containers have ever been spawned

• Agent images are present locally (nanoclaw-agent:latest, nanoclaw-agent-v2-<hash>:latest), so no image build issue

Things I've tested

• Multiple fresh DM rooms (6+) — chat appears in chats table, no registration follows

• Trigger as first chars of message: @Andy hello (plain text, mention pill removed)

• NANOCLAW_REQUIRE_TRIGGER=false

• Fresh MATRIX_ACCESS_TOKEN regenerated via password login

• Wiped /mnt/cache/appdata/nanoclaw/data/matrix-crypto-store/ and restarted to fix initial E2E key issues (this worked — decryption is now clean)

• Confirmed ai-local Docker network exists

• Confirmed Docker socket is mounted

Filtered NanoClaw-only log output around a fresh message arrival

[12:10:11.462] INFO (1): Matrix invite auto-accepted
    roomId: "!xsopKMBPbJldMQcWYc:matrix.org"
[12:10:13.188] INFO (1): Decrypted event received
    eventId: "$UriIj45vGFeFS55aiJF8ulZZpi3lkbYbjv27lmKXauY"
    type: "m.room.message"
    encrypted: true
    roomId: "!xsopKMBPbJldMQcWYc:matrix.org"

…then silence apart from sync polls and periodic crypto-store persistence. No application-level logging beyond this point.

Database state after sending several messages across rooms

sql

SELECT * FROM chats;
-- 6 rows, all matrix rooms, populated correctly

SELECT * FROM registered_groups;
-- empty

SELECT * FROM messages;
-- empty

It looks to me like the message handler is receiving and decrypting events fine, but the path from "event decrypted" → "store message + register group + invoke agent" isn't connected (or is silently bailing very early) on this install. Could it be related to the Matrix-only setup, the OAuth token vs API key auth, or something about how the crypto store wipe + cross-signing import interacts with the registration flow?

Happy to share the full docker logs, container template (with secrets redacted), or run any further commands. Thanks for taking a look.

On 5/12/2026 at 2:54 AM, nathan9214 said:

I did get it working but with a lot of tweaking. I am curious if there is a better workflow. Hopefully one more repeatable.

Hey nathan9214, glad you got it working!

Telegram is still in there and should work — it's just not my primary channel so it hasn't had as much real-world testing in this build. Matrix is the native channel in the bitcryptic/nanoclaw template and tends to be the more repeatable path if you're open to it.

That said, if Telegram is your preference, stick with it. The tweaking you did to get it running is likely the right approach for now. We're planning to re-align with upstream once their v1→v2 migration stabilises — that work is actively in progress over at qwibitai/nanoclaw — so the Telegram experience should improve as things settle.

What did you end up having to tweak? Would be useful to know so I can document it properly for others.

On 5/12/2026 at 12:16 PM, jackmc said:

Hi BitCryptic, thanks for the project and the template work.

I've hit a wall getting NanoClaw responding on Matrix and have done a fair bit of diagnostic work. Hoping you can spot what's wrong — happy to provide anything else useful.

Setup

• NanoClaw v1.3.0 (image: bitcryptic/nanoclaw:latest, container ID 4fd55fe1a417)

• Installed via Community Apps on Unraid

• Matrix-only (no Telegram configured)

• Auth via CLAUDE_CODE_OAUTH_TOKEN (no ANTHROPIC_API_KEY set)

• NANOCLAW_DOCKER_NETWORK=ai-local (network exists and is reachable)

• AppData at /mnt/cache/appdata/nanoclaw/

• Default trigger @Andy, bot user @nectaron-andy:matrix.org, homeserver matrix.org

What works

• Container starts cleanly, no errors

• Matrix invites auto-accept

• Crypto store bootstraps, cross-signing keys imported, device verifies, key backup activates

• Incoming messages decrypt successfully — logs show Decrypted event received with the correct room ID and event ID

• chats table in messages.db populates with each new room

What doesn't work

After Decrypted event received, nothing happens. No registration, no trigger evaluation, no agent spawn, no error. Just sync polling resumes.

• registered_groups table is empty across all attempts

• messages table is empty — incoming messages are never persisted

• /mnt/cache/appdata/nanoclaw/logs/ is empty

• /mnt/cache/appdata/nanoclaw/groups/ is empty

• docker ps -a shows only the main NanoClaw container — no agent containers have ever been spawned

• Agent images are present locally (nanoclaw-agent:latest, nanoclaw-agent-v2-<hash>:latest), so no image build issue

Things I've tested

• Multiple fresh DM rooms (6+) — chat appears in chats table, no registration follows

• Trigger as first chars of message: @Andy hello (plain text, mention pill removed)

• NANOCLAW_REQUIRE_TRIGGER=false

• Fresh MATRIX_ACCESS_TOKEN regenerated via password login

• Wiped /mnt/cache/appdata/nanoclaw/data/matrix-crypto-store/ and restarted to fix initial E2E key issues (this worked — decryption is now clean)

• Confirmed ai-local Docker network exists

• Confirmed Docker socket is mounted

Filtered NanoClaw-only log output around a fresh message arrival

[12:10:11.462] INFO (1): Matrix invite auto-accepted
    roomId: "!xsopKMBPbJldMQcWYc:matrix.org"
[12:10:13.188] INFO (1): Decrypted event received
    eventId: "$UriIj45vGFeFS55aiJF8ulZZpi3lkbYbjv27lmKXauY"
    type: "m.room.message"
    encrypted: true
    roomId: "!xsopKMBPbJldMQcWYc:matrix.org"

…then silence apart from sync polls and periodic crypto-store persistence. No application-level logging beyond this point.

Database state after sending several messages across rooms

sql

SELECT * FROM chats;
-- 6 rows, all matrix rooms, populated correctly

SELECT * FROM registered_groups;
-- empty

SELECT * FROM messages;
-- empty

It looks to me like the message handler is receiving and decrypting events fine, but the path from "event decrypted" → "store message + register group + invoke agent" isn't connected (or is silently bailing very early) on this install. Could it be related to the Matrix-only setup, the OAuth token vs API key auth, or something about how the crypto store wipe + cross-signing import interacts with the registration flow?

Happy to share the full docker logs, container template (with secrets redacted), or run any further commands. Thanks for taking a look.

Great diagnostics — you've basically pinpointed it. The most likely culprit is a path mismatch in HOST_PROJECT_ROOT.

This variable tells NanoClaw where its appdata lives on the host (not inside the container), because it needs to pass correct volume mount paths when spawning agent containers via the Docker socket. Without it resolving correctly, the path from "event decrypted" → "register group + persist message + spawn agent" fails silently at the point it tries to construct the container args — which matches exactly what you're seeing.

Check what you have set for HOST_PROJECT_ROOT and verify it matches where Unraid has actually placed the appdata. The template defaults to /mnt/cache/appdata/nanoclaw but depending on your cache pool name or appdata share configuration it could be something different on your system — /mnt/user/appdata/nanoclaw is a common variation. You can confirm the real path with:

bash

ls /mnt/cache/appdata/nanoclaw

If that returns nothing, try /mnt/user/appdata/nanoclaw and update the template variable to match.

One other thing worth flagging while you're in the template — Anthropic has deprecated OAuth token auth for Claude Code in automated/non-interactive contexts. Even once agent containers are spawning correctly, CLAUDE_CODE_OAUTH_TOKEN won't get you a working agent. You'll need either an ANTHROPIC_API_KEY from console.anthropic.com, or if you're running Ollama or LiteLLM locally, you can use a per-group provider override (NANOCLAW_PROVIDER_BASE_URL + NANOCLAW_PROVIDER_API_KEY + NANOCLAW_PROVIDER_MODEL) to route agent sessions to a local model instead.

Everything else you've described looks healthy — decryption is clean, the network exists, the Docker socket is mounted, and agent images are present. The OAuth situation aside, the HOST_PROJECT_ROOT path mismatch should be the only structural issue.

Your post has also prompted us to update our template docs to make both of these requirements clearer — appreciate the thorough writeup, it's exactly the kind of feedback that helps.

Give it a restart with both fixes applied and let me know what you see. If agent spawning still doesn't fire, grab the full docker logs output from a fresh message send and I'll dig further.

Edited May 13May 13 by BitCryptic
Updated as I had overlooked the option of running Ollama or other local/alternate agents in lieu of the deprecated OAUTH support from Anthropic

This container must set a chat channel while starting? Uhmmm...