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
Install nanoclaw-aio on Unraid in a few clicks.
Find nanoclaw-aio in Community Apps on your Unraid server, review the template, and click Install. Unraid handles the Docker app or plugin setup from the published template.
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