All apps · 0 apps
nanoclaw-aio
Docker app from JSONbored's Repository
Overview
NanoClaw is a Telegram-first AI agent orchestrator for running Claude-powered assistant workflows from chat.
All-In-One Unraid Editionnanoclaw-aio packages NanoClaw v2 into one Unraid-first container and uses the paired [code]jsonbored/nanoclaw-agent[/code] helper image for isolated agent work.
Quick Install (Beginners)
- Install this template and leave [code]Appdata Directory[/code] and [code]Host Appdata Path[/code] aligned unless you intentionally use a custom appdata path.
- Set [code]TELEGRAM_BOT_TOKEN[/code] from BotFather.
- Set [code]ANTHROPIC_API_KEY[/code] or one of the advanced Claude credential options.
- Start the container and watch the logs for [code]PAIR_TELEGRAM_CODE[/code].
- Send that pairing code to your Telegram bot to pair the main chat.
Power Users (Advanced View)
- Advanced View exposes Claude credential aliases, OneCLI gateway settings, helper image overrides, concurrency/timeouts, logging, and assistant identity controls.
- Keep [code]CONTAINER_IMAGE[/code] and [code]CONTAINER_IMAGE_BASE[/code] on the JSONbored defaults unless you build and maintain your own compatible agent helper image.
- [code]NANOCLAW_HOST_APPDATA_DIR[/code] must match the host-side path for [code]/appdata[/code] because nested helper containers are launched through the host Docker daemon.
Important Notes
- This template is marked beta while the NanoClaw v2 runtime gets more real-world Unraid soak time.
- The Docker socket mount is an advanced opt-in setting because NanoClaw launches paired helper containers through the host Docker daemon, which grants host-level Docker control. NanoClaw cannot run helper containers until that mount is enabled.
- Persistent databases, logs, groups, env files, and channel state live under [code]/appdata[/code].
Readme
View on GitHubnanoclaw-aio
NanoClaw packaged as a Telegram-first, Unraid-oriented AIO container.
This repo ships one installable Community Apps template and two container images from the same source repo:
jsonbored/nanoclaw-aio: the Unraid app containerjsonbored/nanoclaw-agent: the nested helper image spawned by NanoClaw for isolated agent work
nanoclaw-agent is not a separate Community Apps template right now. It is a
sandbox/helper image used by nanoclaw-aio.
Current Release
- Upstream NanoClaw:
nanocoai/nanoclawv2.0.64 - Upstream commit:
0683c6ec589ec0df74c2a3d99f9544127317b490 - Channels branch commit:
36fb78092c27737a2313c07244748a98b26c7d03 - AIO image tag:
v2.0.64-aio.4 - Agent helper image tag:
v2.0.64-agent.2
NanoClaw main may move ahead of the latest release. This package tracks stable
upstream releases, not unreleased main.
What This Image Includes
- NanoClaw v2 pinned to the current stable upstream release.
- A Telegram-first control surface for starting and managing agent work.
- A paired
jsonbored/nanoclaw-agenthelper image for isolated task containers. - A Docker-socket sibling-container model, matching NanoClaw v2's current runtime architecture.
- Persistent appdata for databases, logs, groups, channel state, generated env files, and the host-visible runtime source used by helper containers.
- A vendored Telegram channel adapter and pinned channels branch commit so first
boot does not depend on a runtime
git fetch. - A validated Unraid XML template in
nanoclaw-aio.xml.
Beginner Install
- Install the
nanoclaw-aiotemplate from Unraid Community Applications. - Keep the default
/appdatapath unless you also updateNANOCLAW_HOST_APPDATA_DIR. - Mount
/var/run/docker.sock. - Set
TELEGRAM_BOT_TOKEN. - Set one Claude credential:
ANTHROPIC_API_KEYCLAUDE_CODE_OAUTH_TOKENANTHROPIC_AUTH_TOKEN
- Start the container and watch logs for
PAIR_TELEGRAM_CODE. - Send that code to your Telegram bot to pair the main chat.
The template is marked beta while the v2 wrapper gets more real-world Unraid runtime coverage.
Power User Surface
The Unraid template keeps advanced NanoClaw controls visible without making them required for first boot:
- Claude/Anthropic credentials and
ANTHROPIC_BASE_URL - OneCLI endpoint and API key overrides
- helper image overrides through
CONTAINER_IMAGEandCONTAINER_IMAGE_BASE - container timeout, idle timeout, max output size, prompt message limit, and max concurrent container controls
- assistant identity settings
- timezone through
TZ
The default helper image is:
CONTAINER_IMAGE=jsonbored/nanoclaw-agent:v2.0.64-agent.2
CONTAINER_IMAGE_BASE=jsonbored/nanoclaw-agent
Advanced users can override those values if they build their own helper image.
The Community Apps template still installs only nanoclaw-aio.
Runtime Notes
NanoClaw v2 controls agents through Telegram and launches short-lived helper containers through Docker. On Unraid that means:
/appdatapersists databases, logs, groups, channel state, env files, and host-visible runtime source used by helper containers./var/run/docker.sockis required so the AIO container can startjsonbored/nanoclaw-agentsibling containers.NANOCLAW_HOST_APPDATA_DIRmust match the host path mounted to/appdata; the default is/mnt/user/appdata/nanoclaw-aio.- First boot waits for
TELEGRAM_BOT_TOKENand one Claude credential, then emits a Telegram pairing code in the container logs.
Docker socket access is host-level trust. This wrapper makes that requirement explicit instead of hiding it.
If you used an older v1 wrapper image, read
docs/migration-v2.md before following latest.
Publishing and Releases
App repo publishing is controlled by aio-fleet from this repo's
.aio-fleet.yml. Formal GitHub Releases use the AIO image
version, while the helper image ships on the same release train.
jsonbored/nanoclaw-aio and ghcr.io/jsonbored/nanoclaw-aio publish:
latestv2.0.64v2.0.64-aio.4sha-<commit>
jsonbored/nanoclaw-agent and ghcr.io/jsonbored/nanoclaw-agent publish:
latestv2.0.64v2.0.64-agent.2sha-<commit>
See docs/releases.md for the release model.
Validation
Local source validation:
python -m pytest tests/template
xmllint --noout nanoclaw-aio.xml
Container validation:
python -m pytest tests/integration -m integration
The integration suite builds both images, verifies missing-config and smoke-mode behavior, checks appdata persistence, checks the configured agent image, and confirms a missing Docker socket produces a clear waiting state.
Support
- AIO repo: JSONbored/nanoclaw-aio
- Upstream app: nanocoai/nanoclaw
- Issues: JSONbored/nanoclaw-aio issues
Funding
If this saves you time, support it here:
Star History
Requirements
Download Statistics
Related apps
Explore more like this
Explore allDetails
jsonbored/nanoclaw-aio:latestRuntime arguments
- Network
bridge- Shell
sh- Privileged
- false
Template configuration
Persistent NanoClaw data: databases, logs, groups, channel state, env files, and host-visible runtime files for nested agent containers.
- Target
- /appdata
- Default
- /mnt/user/appdata/nanoclaw-aio
Advanced opt-in security-sensitive mount. NanoClaw v2 needs the Docker socket to spawn nested jsonbored/nanoclaw-agent helper containers, which grants host-level Docker control access.
- Target
- /var/run/docker.sock
Bot token from @BotFather. After startup, send the PAIR_TELEGRAM_CODE from the logs to this bot.
- Target
- TELEGRAM_BOT_TOKEN
Claude API key. Use this or one of the advanced Claude credential options.
- Target
- ANTHROPIC_API_KEY
Host-side path matching the Appdata Directory mount. Nested agent containers need this host path when the AIO talks to the host Docker daemon.
- Target
- NANOCLAW_HOST_APPDATA_DIR
- Default
- /mnt/user/appdata/nanoclaw-aio
Optional Claude Code OAuth-style credential. Use instead of ANTHROPIC_API_KEY when applicable.
- Target
- CLAUDE_CODE_OAUTH_TOKEN
Optional Claude/Anthropic auth token for runtimes that expect ANTHROPIC_AUTH_TOKEN.
- Target
- ANTHROPIC_AUTH_TOKEN
Optional Anthropic-compatible API endpoint override.
- Target
- ANTHROPIC_BASE_URL
Optional OneCLI gateway URL for NanoClaw agent credential injection.
- Target
- ONECLI_URL
Optional OneCLI API key.
- Target
- ONECLI_API_KEY
Helper image used for spawned agent containers. Advanced users may point this to a custom built agent image.
- Target
- CONTAINER_IMAGE
- Default
- jsonbored/nanoclaw-agent:v2.0.64-agent.2
Base repository NanoClaw uses when building per-agent customized helper images.
- Target
- CONTAINER_IMAGE_BASE
- Default
- jsonbored/nanoclaw-agent
Agent container timeout in milliseconds.
- Target
- CONTAINER_TIMEOUT
- Default
- 1800000
Idle timeout in milliseconds for keeping agent containers warm after results.
- Target
- IDLE_TIMEOUT
- Default
- 1800000
Maximum captured output from an agent container in bytes.
- Target
- CONTAINER_MAX_OUTPUT_SIZE
- Default
- 10485760
Maximum message history items NanoClaw passes into a prompt.
- Target
- MAX_MESSAGES_PER_PROMPT
- Default
- 10
Maximum number of concurrent NanoClaw agent containers.
- Target
- MAX_CONCURRENT_CONTAINERS
- Default
- 5
NanoClaw log level.
- Target
- LOG_LEVEL
- Default
- info
Assistant trigger name used by NanoClaw. Example trigger: @nanoclaw
- Target
- ASSISTANT_NAME
- Default
- nanoclaw
Set true only when your NanoClaw assistant has its own dedicated channel identity.
- Target
- ASSISTANT_HAS_OWN_NUMBER
- Default
- false
When true, the container starts the pairing-code watcher on first boot.
- Target
- NANOCLAW_AUTO_PAIR_TELEGRAM
- Default
- true
Timezone used by scheduled tasks and formatted timestamps.
- Target
- TZ
- Default
- UTC