Self-host nanoclaw
v2026.10.0Chat-based AI agent with per-session container isolation
- Stars
- 31 118
- RAM
- 4 GB+
- Port
- 3000 (Local webhook server (WEBHOOK_PORT))
What is nanoclaw?
NanoClaw gives you a personal AI agent that lives on a machine you own, and you converse with it through the chat services you already check. Its Node.js host process decides which agent session an inbound message belongs to, appends it to that session's SQLite inbox, and starts a Docker container where the actual model turn happens. Replies land in a matching SQLite outbox that the host polls and sends back over the same channel. Protection comes from the operating system rather than from allowlists inside the app: a container sees only the folders you mount into it, and an outbound gateway attaches credentials to requests so the agent code never handles keys.
Organisation revolves around agent groups. Each group carries its own instruction file, memory tree, container and mount list, and groups never share unless you wire them together. One channel can drive a private agent, several channels can point at the same agent, or you can merge them into one conversation that spans every surface. Chat integrations - Slack, WhatsApp, Telegram, Discord, Signal, Matrix, Teams, iMessage, email and the rest - are not part of trunk; each is a skill you copy into your fork, and model providers work the same way. Anthropic's Claude Code through the Agent SDK comes built in, while Codex, OpenCode and Ollama for local open-weight models are optional and chosen group by group. Alongside answering messages it runs recurring jobs on a schedule, browses and reads web pages, and can create further agents as teammates. Deliberately there are no config files: you fork this comparatively small codebase and have a coding agent reshape it, or run /customize. Conversations stay on your machine, and the anonymous setup reporting can be turned off.
To run it yourself, clone the repository and start bash nanoclaw.sh: the wizard brings in Node.js, pnpm and Docker, parks your model credential in the vault, builds or pulls the container image, and pairs your first channel. A manual pnpm install is documented, plus a team-maintained helper that sets everything up inside an LXC on Proxmox VE. The container runtime is Docker only; budget roughly 4 GB of RAM, Node 22 or newer and git, and remember that the provider bills your model usage. A free vendor account stays optional and is needed only for extras such as the prebuilt hardened image or a managed Slack app.
Should you self-host nanoclaw?
nanoclaw scores 77/100 on selfhost.directory (how scoring works) and ranks #9 of 120 in AI Assistant. It has 31 118 GitHub stars, +187 in the last 30 days.
It shipped 9 stable releases in the past year. The latest, v2026.10.0, came out on 9 October 2026. New versions land roughly every 2 weeks.
Setup is moderate: expect some configuration beyond a single command. It is MIT-licensed and written mostly in Typescript.
Its closest alternative on selfhost.directory is AstrBot (88/100, 47 009 stars). It scores higher overall, so compare the two before you pick. See nanoclaw vs AstrBot side by side.
Features
- Admin CLI
- Agent templates
- Background service install
- Credential gateway (no raw API keys in agents)
- Customization by code change
- Egress LockdownOff by default (NANOCLAW_EGRESS_LOCKDOWN=false).
- Multi-agent Teams
- Multi-channel chat integrationAdapters live on the `channels` branch and are copied into your fork with /add-<channel> skills.
- Multiple model providers
- Per-agent memory and workspace
- Per-group container config
- Per-session container isolation
- Scheduled Tasks
- Terminal CLI channel
- Web search and page fetch
nanoclaw README
An AI assistant that runs agents securely in their own containers. Lightweight, built to be easily understood and completely customized for your needs.
nanoclaw.dev •
docs •
中文 •
日本語 •
한국어 •
•
How to install nanoclaw
Install nanoclaw with Linux
ASSISTANT_NAME, DEFAULT_AGENT_PROVIDER, TZ, LOG_LEVEL, WEBHOOK_PORTgit clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 cd nanoclaw-v2 bash nanoclaw.sh
Runs as a systemd user service (or a nohup wrapper when systemd is unavailable); the wizard installs Docker Engine if missing.
Install nanoclaw with Proxmox VE
bash -c "$(curl -fsSL https://raw.githubusercontent.com/glifocat/nanoclaw-proxmox/nanoclaw-helper-v2.2/ct/nanoclaw.sh)"
Helper script from the team's nanoclaw-proxmox fork creates an unprivileged Debian 13 LXC (2 cores, 8 GiB RAM, 40 GiB disk by default) with nesting and keyctl enabled so Docker can run inside, then installs NanoClaw in it.
How to configure nanoclaw
ASSISTANT_NAME=AndyAssistant name. Also sets the default trigger, `@<name>`.ASSISTANT_HAS_OWN_NUMBER=falseSet `true` when the assistant runs on its own WhatsApp number instead of yours.ONECLI_URLURL of the OneCLI Agent Vault. Read only when the OneCLI gateway is installed.ONECLI_API_KEYAPI key for the vault. Read only when the OneCLI gateway is installed. See Credentials.TZ=system timezone, else UTCIANA timezone for scheduled tasks and timestamps. Invalid values are skipped, not errored. Injected into every agent container at spawn.
nanoclaw releases & version history
AI summary NanoClaw now follows published releases for updates
NanoClaw 2026.10.0 is the first release with calendar version numbers and the first one /update-nanoclaw installs by default: updates now follow published releases instead of the tip of main. It was tested first as 2026.10.0-rc.1 and 2026.10.0-rc.2 on the beta channel. It also makes updates and rollbacks more dependable, lets Iron Proxy reach a keyless local model over plain HTTP, routes the service through an outbound proxy when you have one, and shows Claude's own reason when a run fails. Iron Proxy installs need one setup rerun, so check the section below before you update.
⚠️ Before you update
- [BREAKING] OneCLI installs: upgrade the OneCLI gateway to exactly 1.42.0, which closes a credential-injection bypass.
/update-nanoclawnever upgrades a running gateway, so this step stops the update until it is done. Followdocs/onecli-upgrades.mdin your install (the same guide on GitHub): its detect step says when it does not apply (Iron Proxy installs skip it); otherwise save 1.42.0 as the gateway version, upgrade, confirm that the running image is 1.42.0, and note the old version for its rollback step. Do not go past 1.42.0: OneCLI 1.43 and later break assigning credentials to agents and are not supported yet. New installs already get 1.42.0. /update-nanoclawnow installs the newest release, not the tip ofmain. The channel is set byNANOCLAW_UPDATE_CHANNELin.env:stable(the default) follows releases,edgefollowsmainas before, andbetatakes release candidates when there are any. Your first update after this release still runs your current update steps, so it lands on the tip ofmain, which is this release only until new changes merge; from then on, updates follow the channel. An install that is already newer than the latest release is never moved back: the updater asks whether to keep followingmainor wait for the next release, and saves the answer. To choose yourself later, runpnpm exec tsx scripts/update-nanoclaw.ts set-channel --channel edge(orstable).- Iron Proxy installs: rerun the Iron setup once after updating. It rebuilds the proxy on upstream v0.52.0 (expired proxy certificates are regenerated, host rules match case-insensitively), moves the approval bridge to
@grpc/grpc-js1.14.5 (fixes GHSA-m9gg-hp2v-232j and GHSA-f596-whhp-79r4), and letsgit clone/fetchand the agent browser authenticate through the proxy. Runpnpm exec tsx .claude/skills/add-iron-proxy/scripts/setup.ts --with-control. The agent browser now trusts the gateway's certificate, so HTTPS pages behind Iron load: installs that build their own agent image get it from the image rebuild in/update-nanoclaw, while installs that pull the hardened image get it only with the next image (until then the browser stays broken there; the agent still starts). OneCLI installs need nothing.
✨ New
- Updates follow release channels. Choose
stable,betaoredgeper install; the channel and the exact release are recorded indata/upgrade-state.json, so support can see what an install tracks. - With Iron Proxy, a keyless model on the same machine works over plain HTTP. Enter
http://host.docker.internal:<port>/v1and restart; setup checks that the port answers like a model server, only that port and the OpenAI inference routes are reachable, and requests to it no longer ask for approval on every call. Models that need a key still needhttps://on a public DNS name. - The service can reach the internet through an outbound proxy. It now uses
HTTPS_PROXY,HTTP_PROXYorALL_PROXYandNO_PROXYfrom your setup shell or.env; a OneCLI gateway on a local address is added toNO_PROXYautomatically. Needs Node 22.21+ or 24.5+, and setup warns if your Node ignores the proxy. - A failed Claude run tells you why. For known failures such as an invalid API key, the chat shows Claude's short message (for example "Invalid API key · Fix external API key") and who can fix it, instead of "The agent run failed".
- Iron Proxy can skip the approval card for reads that send no credential. Set
NANOCLAW_GATEWAY_UNCREDENTIALED_READS=truein.env, and a GET or HEAD request with no body skips the card when no stored credential could apply to its host; the egress allowlist still limits where it can go. Off by default. If you already reran the Iron setup on a release candidate, rerun it once more to use this, because it rebuilds the approval front; until then every card stays.
🛠️ Fixes
/update-nanoclawis more dependable. A failed update no longer deletes half ofdata/when it rolls back: the snapshot is swapped in by rename, and if a restore still fails nothing is deleted and the error prints the commands that finish it. It works again from 2.4.0 (it stopped with "Cannot find module"), detects the installed gateway even when pnpm prints a warning, keeps Iron Proxy running across the update, and no longer reports success while the old service is still running. A rollback now stops the host that is actually running and stops agent containers before restoring your data. Updates that bring a new tsx or esbuild no longer crash at the end of cutover on installs with a gateway (the fix is in the update controller, so it covers the update that brings it). A fresh install can now be updated without manual commits: setup commits the files it adds as localsetup: apply <skill>commits (setNANOCLAW_SETUP_COMMIT=0to skip them). When an update changes only your gateway's skill files, it now refreshes the gateway's host code too.- Claude turns are cheaper again. New Claude groups no longer default to the
Conciseoutput style, which stopped the prompt cache from reading the conversation back, so every turn paid to cache it again; the concise instruction now lives in the agent'sCLAUDE.md. A group that already hasConcisekeeps it: setoutputStyletodefault(or delete the key) indata/v2-sessions/<agent-group-id>/.claude-shared/settings.json. - Agents behave better in chats. The typing indicator stays on while Claude writes a long answer, agents no longer trade "The agent run failed" messages with each other forever, and they read each turn's subject from their own message and history, asking when a bare "this" is ambiguous. Deleting an agent with
ncl groups deletenow stops its container within about a minute. - Setup is clearer when something goes wrong. A failing skill step shows its own reason, Codex and OpenCode installs are no longer offered the Claude CLI, a failed host restart says why the host is not ready, and the setup log records whether the assistant answered the first test message. OpenCode setup checks a local model URL against your gateway at the prompt, Iron Proxy setup skips a malformed allowlist entry and says how to fix it, and on arm64 Linux it stops early, with the command to turn on emulation, when Docker cannot run the Iron Control image. Setup's OneCLI step works under a strict
077umask, and uninstalling removes the Iron Control database so a reinstall in the same folder starts clean. - OneCLI gateway upgrades now stay on 1.42.0. The upgrade guide saves the version in
~/.onecli/.envand checks which image is running, so a later restart cannot move the gateway to a newer release; 1.43 and later are not supported yet. - The OneCLI upgrade guide is safer when the gateway version is missing or too new. Its save commands now stop on an empty version, which used to make Docker Compose run the newest gateway and change its database, and the guide backs up the gateway database before the upgrade. If a newer gateway has already run, the guide sends you back to the pinned version instead of the rollback step, which could start the newer one again.
- Updates on macOS no longer fail and roll back when the service is slow to stop. The updater now waits for NanoClaw to exit fully before it continues, instead of failing with "Bootstrap failed: 5: Input/output error".
- A fresh install that adds a channel starts again after a restart. Setup's own local commits now carry the upgrade marker forward, so the startup check no longer stops NanoClaw with "update did not go through the supported path" after the first reboot or update.
- Dial can be added again on OneCLI gateway 1.42.0.
/add-dial-toolnow scopes Dial with a OneCLI policy rule instead of the legacy rules the gateway rejects, and publishes it before the Dial key is stored. Older gateways and 1.43+ stop with a message naming the supported version. - Smaller fixes. OpenCode agents avoid a Bun hang in the memory hook;
send_cardno longer breaks requests to llama.cpp-served models (non-ASCII link URLs are encoded automatically); OneCLI credential errors during setup name the credential being set up instead of always saying "OpenCode"; a scheduled-task pre-script that hits its 30 s timeout now stops its child processes too; logging a circular object or a BigInt no longer crashes the host;ncl approvals helpandncl dropped-messages helplist exactly the values the host writes;CLAUDE_CODE_AUTO_COMPACT_WINDOWset in.envor the service environment now reaches Claude agents (it was ignored); WhatsApp linking no longer hangs when WhatsApp rate-limits setup, and stops at once with the reason if the current WhatsApp Web version cannot be fetched; Node 26 no longer prints amodule.register()warning; the OneCLI upgrade guide checks the gateway at the address inONECLI_URL, so it works on Linux installs where the gateway listens on the Docker bridge; and the/add-imessagelocal backend on a Mac openschat.dbagain (if you installed it before, rerun/add-imessageand chooselocal).
🔒 Security
- WhatsApp uses Baileys 7.0.0-rc14, which fixes a critical message-spoofing flaw (GHSA-qvv5-jq5g-4cgg).
/update-nanoclawmoves existing WhatsApp installs to the fixed version, and linked devices do not need to link again. - Agents can no longer redirect host file operations outside their own folders. A compromised or prompt-injected agent could swap a directory inside its session or group folder for a symlink and make the host read, write or delete files elsewhere as the host user. No configuration change is needed. See GHSA-frvf-5rf5-89fq, GHSA-7wx5-9p7v-wvhp, GHSA-vwj5-j44r-v364 and GHSA-9j3v-9hwg-v896; thanks to @KyleCard, @roisec, @prathish-ks and @sajdakabir for reporting.
- Setup downloads the OneCLI installer over HTTPS only. The address used to have no
https://, so on an untrusted network the download could be swapped during setup. Existing installs need nothing. See GHSA-628g-jj3x-6mp9; thanks to @ShaharGigi for reporting it. - Only admins can run
/clearand/upload-tracenow, however the command is typed. A group member who was not an admin could get past the permission check by adding text to the end of a command, such as the@botnameTelegram adds in group chats. The check and the agent now read commands the same way, including the other names the Claude SDK accepts for them (like/resetfor/clear). See GHSA-g3gp-6777-8p9g; thanks to @sajdakabir for reporting it. - Group-scoped agents can no longer read other agent groups through
ncl. An empty or differently spelled group flag (for example--agent-group-idnext to--agent_group_id) got past the group check and let an agent list other groups' destinations. Installs with one agent group were not affected. See GHSA-r7fr-2v6h-rhqf; thanks to @sajdakabir for reporting it. - Mattermost setup checks the owner's user ID before using it. Setup took this ID from the Mattermost server and used it in a command without checking it, so a malicious server, or someone who could change traffic to a server on plain
http://, could run commands as the user running setup. Existing installs need nothing. See GHSA-8w49-2gv4-3x6w; thanks to @ShaharGigi for reporting it. - Host logs keep a value's own redaction (its
toJSON()) even when the logged data also holds a BigInt or a circular reference. - Setup's debugging helper asks before it runs commands or edits files. Claude's headless helper is read-only.
- Outbound proxy settings, which can include a password, are kept in an owner-only file instead of the service definition. If you use an authenticated proxy, rerun setup's service step (
pnpm exec tsx setup/index.ts --step service) to move it out of your existing service file. - Discord's local event relay only accepts events from NanoClaw's own Discord connection, so other programs on the same machine can no longer send it fake button clicks. No action needed.
🔧 For custom installations
- Version numbers are now calendar-based (
YYYY.M.PATCH). 2026.10.0 follows 2.4.0 and sorts after it, so tools that compare versions keep working; a dependency range such as^2will not match it. Release tags stayvX.Y.Zand annotated. - Forks that merge
mainby hand can keep doing so; to keep/update-nanoclawonmaininstead of releases, runpnpm exec tsx scripts/update-nanoclaw.ts set-channel --channel edgeonce. - Provider contracts can list exact model endpoints. A provider skill sets
modelAuthoritiestohost:portpairs that skip the gateway's default approval, asmodelDomainsdoes for whole domains. - The published agent image is unchanged in this release. Installs that pull the image keep the 2026-08-25 build; the agent-runner dependency refresh in this release reaches them with the next image, built from this release's tag. Installs that build the image locally get it now.
New Contributors
- @barnuri made their first contribution in #3895
- @daviddl9 made their first contribution in #3969
- @drsmk238 made their first contribution in #3989
Contributors
Thanks to everyone who landed work in this release:
- fix(cli): list every approval status and drop reason the host writes by @glifocat in #3882
- feat(agent-runner): explain inbound message blocks in the chat system prompt by @Koshkoshinsk in #3890
- fix: seed Claude's default output style, not Concise, which defeated prompt caching by @gavrielc in #3917
- fix(agent-runner): keep send_card url pattern parseable by llama.cpp grammars by @barnuri in #3895
- fix(iron-proxy): skip invalid allowed-hosts entries instead of aborting setup by @glifocat in #3915
- fix(cli): drop unknown_sender_public from the dropped-messages reason list by @glifocat in #3889
- test(community-portal): wait for the journal to clear instead of sleeping by @glifocat in #3892
- fix(agent-runner): keep the heartbeat alive while Claude streams a long block by @glifocat in #3893
- fix(setup): keep the Claude CLI offer to Claude installs by @glifocat in #3884
- test(webhook): recover on the fixture-owned port by @glifocat in #3803
- fix(update): load the update controller without setup/ or node_modules by @glifocat in #3913
- fix(agent-runner): never answer a failure notice with another by @glifocat in #3908
- fix(opencode): run the memory hook with async spawn so bun test cannot wedge by @glifocat in #3841
- fix(setup): log the first-chat ping result and the real OpenCode auth duration by @glifocat in #3905
- fix(setup): never clip a readiness probe to the deadline by @glifocat in #3887
- fix(setup): detect installed gateways without parsing nested pnpm output by @glifocat in #3910
- test(delivery): seed one session past the cap in the drain test by @glifocat in #3945
- fix(skill-apply): show a failed step's own error instead of a generic bounce by @glifocat in #3946
- fix(update): keep gateway-owned containers through cutover and residue reaping by @glifocat in #3948
- test(agent-runner): spawn bun children asynchronously so CI stops hanging in spawnSync by @glifocat in #3959
- fix(add-onecli): name the credential, not the provider, in adapter errors by @glifocat in #3960
- fix(scheduling): kill the whole process group when a pre-task script times out by @glifocat in #3957
- fix(setup): restrict failure-assist agents on a live install by @glifocat in #3920
- fix(iron-proxy): remove Iron Control's database on uninstall by @glifocat in #3883
- fix(host): stop containers whose session or agent group was deleted by @glifocat in #3947
- fix(iron-proxy): stop early on arm64 engines that cannot run amd64 images by @glifocat in #3953
- docs(gateways): correct what the credential reread refuses in two comments by @glifocat in #3954
- docs(opencode): keep gateway notes in the gateway skills by @glifocat in #3955
- fix(log): never throw when a log value cannot be JSON-serialized by @glifocat in #3958
- fix(update): refuse cutover when the service liveness probe itself fails by @glifocat in #3962
- fix(container): refresh agent-runner lockfile to clear transitive advisories by @glifocat in #3974
- fix(update): rollback stops the live nohup host and drains agent containers by @glifocat in #3956
- feat(gateway): let a provider declare exact host:port model endpoints by @glifocat in #3964
- fix(opencode,iron): check the model URL against the selected gateway at the prompt by @glifocat in #3965
- feat(iron): allow a keyless model on this machine over plain HTTP by @glifocat in #3966
- ci: pin workflow actions and cosign to exact versions by @glifocat in #3968
- fix(setup): let the host service reach the internet through an HTTPS proxy by @barnuri in #3901
- build(deps): bump tsx to 4.23 to stop Node 26 module.register warning by @glifocat in #3977
- test(onecli): make unsafe-directory permissions test umask-independent by @glifocat in #3979
- build(deps): bump grpc to 1.83.2 in the Iron front proxy by @glifocat in #3981
- build(deps): pin Iron Proxy to v0.52.0 by @glifocat in #3982
- test(update): remove the data symlink with unlinkSync, not rmSync by @tchopoorian in #3963
- fix(agent-runner): show the Claude SDK's own failure notice instead of the generic one by @glifocat in #3994
- fix(iron-proxy): send a Basic challenge with the front proxy's 407 by @daviddl9 in #3969
- fix(update): restore the snapshot by rename so a rollback never half-deletes data/ by @glifocat in #4012
- feat(release): self-approved x.y.z-rc.N pre-releases; widen stable approvers by @glifocat in #3987
- fix(setup): keep proxy credentials out of readable service files by @glifocat in #3985
- fix(setup): commit applied skill files so a fresh install can update by @glifocat in #3997
- build(deps): bump @grpc/grpc-js to 1.14.5 in the Iron approval bridge by @glifocat in #4005
- fix(onecli): pin the gateway to 1.42.0 for the host-enforcement bypass fix by @drsmk238 in #3989
- fix(chat-sdk): authenticate the loopback Gateway webhook by @glifocat in #4013
- test(setup): mirror host pnpm patches and overrides in the nested-pnpm probe by @glifocat in #4001
- fix(add-imessage): open chat.db under Node with core's prebuilt better-sqlite3 by @glifocat in #4008
- ci(labels): run the area labeler after label-pr, not in parallel by @glifocat in #3912
- fix(update): load gateway helpers before cutover swaps node_modules by @glifocat in #4016
- docs(contributing): write down the core-or-fork rule by @glifocat in #4011
- fix(update): refresh the installed gateway when only its skill payload changed by @glifocat in #3988
- feat(update): follow release tags by default via update channels by @glifocat in #3986
- chore(release): v2026.10.0-rc.1 by @glifocat in #4025
- fix(add-whatsapp): pin Baileys 7.0.0-rc14 for the message-spoofing fix by @glifocat in #4024
- docs(add-onecli): check the gateway at ONECLI_URL in the upgrade guide by @glifocat in #4028
- fix(log): keep nested toJSON redaction when a value holds a BigInt or a cycle by @glifocat in #3983
- fix(claude): pass CLAUDE_CODE_AUTO_COMPACT_WINDOW from the host into the container by @glifocat in #3999
- fix(container): trust the gateway CA in the agent browser by @glifocat in #3998
- ci: merge agent-image pin bumps by hand, drop the auto-approver by @glifocat in #4009
- fix(setup): fetch the current WhatsApp Web version before linking by @glifocat in #4017
- test(setup): reuse exec-checked stubs in the restart readiness tests by @glifocat in #4035
- fix(onecli): hold the gateway on 1.42.0 and stop /add-dial-tool on 1.42+ by @glifocat in #4036
- fix(update): wait for the launchd host to exit after bootout by @glifocat in #4037
- chore(release): v2026.10.0-rc.2 by @glifocat in #4038
- fix(onecli): upgrade guide refuses an empty gateway pin by @glifocat in #4039
- ci: let Dependabot see skill-pinned npm versions by @glifocat in #4007
- fix(onecli): migration warning points back to the pin, not the old version by @glifocat in #4041
- feat(gateway): skip the approval card for reads that carry no credential by @glifocat in #4015
- fix(setup): carry the upgrade marker across setup's local commits by @glifocat in #4051
- fix(add-dial-tool): scope Dial through the OneCLI policy API (gateway 1.42) by @glifocat in #4052
- fix(setup): use a full URL and explicit curl options for the OneCLI installer by @glifocat in #4059
- fix(add-mattermost): check the owner lookup result during setup by @glifocat in #4060
- fix(cli): normalize ncl arguments once in dispatch by @glifocat in #4061
- fix(commands): parse slash commands once for the gate and the runner by @glifocat in #4062
- fix(host): open session, skill and run-log directories by descriptor by @glifocat in #4063
- test(drivers): keep fs.constants in the driver tests' fs stub by @glifocat in #4064
- chore(release): v2026.10.0 by @glifocat in #4065
Full Changelog: v2.4.0...v2026.10.0
AI summary Credential gateways, community-portal setup, and agent instruction rework
NanoClaw 2.4.0 adds credential gateways installed through skills (OneCLI stays the default, Iron Proxy is new), community-portal setup for Echo's hardened image and a managed Slack app, install-wide and per-group model and speed controls, a Mattermost channel, and a reworked OpenCode provider. Agents now receive all of their capability instructions, replies stay in the thread they answer, and host restarts and /update-nanoclaw are more reliable. The default Claude model moves to Opus 5.5 and new Codex threads to gpt-6-astra, so check the section below before you update.
⚠️ Before you update
- [BREAKING] Custom source that composes agent instructions must move to the new module.
CLAUDE.mdwas a list of@imports into/app, and Claude Code silently drops imports that resolve outside the project directory, so eight of nine instruction sections never reached the model; it is now one flat file with every source inlined, shared with the Codex provider.src/claude-md-compose.tsis nowsrc/project-doc-compose.ts,composeGroupClaudeMd(group)becamecomposeGroupProjectDoc(group, groupDir, spec), and the/app/CLAUDE.mdand/workspace/agent/.claude-fragmentsmounts are gone. Migration: rungrep -rn --exclude='*.test.ts' "claude-md-compose\|composeGroupClaudeMd\|claude-fragments" src/ setup/ scripts/; no hits means nothing to do, otherwise repoint the import and passDEFAULT_PROJECT_DOCas the third argument. Then clear the inert leftovers once withrm -rf groups/*/.claude-fragments groups/*/.claude-shared.md. Standard installations need no source edits; see docs/release-2.4-update.md. - [BREAKING] Forks that merge upstream by hand must install their credential gateway before restarting. Credential gateways now install through skills:
/add-oneclisupplies OneCLI and/add-iron-proxyadds optional Iron Proxy support, with a shared contract owning session lifecycle and human approvals. OneCLI remains the simple-setup default, gateway selection appears only in advanced setup, and upgrades preserve the existing selection. SettingNANOCLAW_GATEWAY_PROVIDERalone does not install its implementation, and the host refuses to start without a registered gateway. Migration:/update-nanoclawmaterializes the selected gateway before cutover; a manual merge must apply/add-onecli(or the selected gateway's skill) before restarting. See gateway migration for detection, verification, and rollback. - Claude groups with no model set move to Opus 5.5, which changes cost and usage-limit burn. API-key installs move from Opus 5, and Pro and Team Standard installs from Sonnet. To keep a model, set
NANOCLAW_DEFAULT_MODELin.envor runncl groups config update --id <group> --model <model>before updating. - Codex groups with no model set start new threads on
gpt-6-astra./add-codexnow pins@openai/codex0.155.1, whose default replaces 0.146.0'sgpt-5.6-sol; existing threads keep the model they started on. To stay on the old model, runncl groups config update --id <group-id> --model gpt-5.6-sol, thenncl groups restart --id <group-id>.NANOCLAW_DEFAULT_MODELwould also hold it but applies to Claude groups too. Existing Codex installs get the new pin and the provider fix below together from/update-nanoclaw, which rebuilds the agent image on installs that build their own. - Claude agents default to a concise tone. A Claude group whose settings do not set an output style now starts with
Concise; the default is written once into the group's Claude settings and an explicit value is never overwritten, so groups that already setoutputStyleare unaffected. To keep or change the tone, setoutputStyleindata/v2-sessions/<agent-group-id>/.claude-shared/settings.json(the group's/home/node/.claude/settings.json); project and local settings still take precedence. - Existing OpenCode installs must refresh the skill payload. The optional
/add-opencodeskill now uses the native provider contracts and the new contract refuses the old payload: re-run/add-opencode, rebuild the agent image, and restart the host and the OpenCode groups. - Cutover stops this install's agent containers itself.
/update-nanoclawno longer times out while an idle agent container is running: it stops the containers with a 10-second grace inside a one-minute bound and names them as it goes, so no manualdocker stopis needed. An agent in the middle of a turn loses that turn, as withncl groups restart.
✨ New
- Iron Proxy is an alternative local gateway.
/add-iron-proxyinstalls Iron Proxy and its Iron Control web console (Secrets, Credentials, OAuth Apps, Principals) on Docker; each request passes front identity and allowlist, then human approval, then stored credentials, before it reaches upstream. Codex works through Iron, including its WebSocket turns, setup can install Codex and pair it under Iron in one run, and a failed credential save names its cause on screen and inlogs/setup.log. See .claude/skills/add-iron-proxy/SKILL.md. - OpenCode can authenticate through Iron Control. It can store API keys and native ChatGPT OAuth credentials there, including token refresh and reauthentication that preserves grants.
- Echo's hardened image and a managed Slack app are set up through the community portal with one browser sign-in. Setup prints one link that covers sign-in, terminal approval and the perk choice, and the install token never passes through the browser. The running host stays linked to your account's cell, so a perk changed in the browser reaches the running agent and a Slack install approved days later finishes on its own. Setup asks each portal question once, including across a resumed or repeated run; Dial and Tavily are not offered. See docs/community-portal.md.
- Two install-wide model knobs.
NANOCLAW_DEFAULT_MODELfills in the model for agent groups that have not set one of their own (a group's own model always wins), andNANOCLAW_FAST_MODE=1turns on the API's fast serving tier for every agent, with faster output at a higher per-token price. Both are read from the host.envwhen container.json is materialized, so a change takes effect at the next container start with no host restart. Installs that set neither are unaffected: neither field is written to container.json and the provider sends exactly the options it sent before. - Per-group serving speed.
ncl groups config update --id <group> --speed fastselects a serving tier the group's provider declares; Claude acceptsstandardandfast, fast mode costs more per token, and--speed ""clears it. Agent callers need approval, as with--timezone. - Agents run on Claude Code 2.1.280. A
cdnow carries over between turns, Monitor watches expire after 30 minutes, resumed agents keep seeing their current name and destinations, and claude.ai account skills and plugins are not synced into agent containers. - The OpenCode provider is reworked.
/add-opencodenow uses host-managed authentication and model selection, native tools and compaction, and reliable cancellation, and setup can install and authenticate it. - Mattermost is a channel.
/add-mattermostinstalls it, can connect to a server you already run, validates and atomically saves its settings, verifies the running bot and server callback, and no longer needs a separately installedjq. - Host restarts keep approvals and delivery state. Approvals, delivery retry counts and session claims now live in the central database instead of host memory: an approval card sent before a restart still resolves after it (a late approve that can no longer be applied gets a follow-up card), overdue approvals expire as "no response" instead of being swept as "host restarted", and a message that keeps failing gives up after its retry limit even across a crash loop. A second host started in the same checkout no longer takes over a running host's
nclsocket, and a host still draining during a restart keeps its sessions until it exits. ncl statusshows the running host process and its connected channel adapters. Setup uses it to confirm that the restarted host is the one it started.- The Slack agents companion skills ship on
main./slack-a2a-roomsand/slack-agent-flownow come with the core source.
🛠️ Fixes
- Codex turns no longer complete with nothing sent. From 0.147.0, Codex starts a turn after about one second without the tools of any MCP server still starting. The provider now waits for every MCP server to finish starting (Codex gives up on one after 30 seconds, as 0.146.0 did) and requires NanoClaw's own tool server: if that server cannot start, the message fails with an error instead of running without its tools.
- Replies stay in the thread they answer. Replies,
send_message,send_file,ask_user_questionandsend_cardland in the thread of the message being answered, not the main channel or a thread that spoke more recently; this covers shared and agent-shared sessions, and replies from a turn longer than 30 minutes stay threaded. - Busy installs stay fast. The host sweep and delivery polls visit up to 8 sessions at a time at a fixed rate, and cross-session ambient context fans out only to a conversation's 8 most recently active threads (within 3 days) after the container wakes, so installs with many sessions or busy channels no longer see reply and task latency grow with size.
- Quoted
.envvalues read the same everywhere. Setup had its own parser that did not strip surrounding quotes, so a hand-editedTZ="America/New_York"orNANOCLAW_TEMPLATE_PATH="/opt/my templates"reached the wizard with the quotes attached and the template path was bridged intoprocess.envunusable; both readers now share the host parser (envValueinsrc/env.ts, the single-key form ofreadEnvFile). /update-nanoclawloads its controller again. It crashed withMODULE_NOT_FOUND; it now also snapshots symlinked data roots by content and is correct on macOS hosts.- Setup is sturdier on Linux. No hang with a system-wide Node, a user-owned npm prefix instead of an invisible sudo, a nohup-started host verified and kept running when user systemd is missing, installers that run under
/bin/shand/bin/bash, a uvx-installed pnpm recovered, and the replacement host verified after a restart. - Concurrent SQLite migrations no longer fail setup or upgrade. Failed registry copies keep existing files, registry skills install from single-branch clones, and installing missing skill files keeps your customizations.
- OneCLI certificate and credential-stub mounts survive host restarts and temp cleanup, and
WEBHOOK_PORTis read from.env. - Conversations reach the right place and stop when asked. Cancelled questions stop promptly, failed provider turns keep partial replies, scheduled-task escalations default to the agent's own channel, and Slack group-DM and multi-instance approval cards name the right conversation and bot.
- Task failures are easier to diagnose.
ncl tasks updaterejects an empty--prompt, and a timed-out pre-task script says so. /add-dialhandles more starting states. It installs the Dial tool on a first-ever install (before any agent exists), echoes what you type at its agent-scope question, and/add-dial-toolcan re-register a rotated key with OneCLI.- Agents know their card options. They are told that
send_cardsupports URL link buttons and that interactive choices needask_user_question.
🔒 Security
- Setup redacts resolved secrets in skill logs and commits related
.envvalues atomically. - The agent image is repinned and the supply-chain gate is enforced. The image is
hardened-2026-08-24and runs Bun 1.4.0, and pnpm's 3-dayminimumReleaseAgegate now takes effect. See docs/hardened-image.md.
🔧 For custom installations
- Chat SDK channels can recover content the adapter left in the raw payload. The bridge drops
message.rawbefore persisting, so anything a platform did not project into its message text was lost; Slack keeps pasted tables inattachments[].blocks[], and an agent saw only the sentence before the table. The optionalextractRawTexthook onChatSdkBridgeConfiglets a channel rescue that content as text before raw is discarded; raw payloads still never reach the database, and a channel without the hook is unaffected. Slack uses it to recover pasted tables: refresh/add-slackto get it. - Custom OpenCode models can declare their limits.
/add-opencodedocumentsOPENCODE_MODEL_CONTEXT_LIMIT,OPENCODE_MODEL_OUTPUT_LIMITandOPENCODE_MODEL_INPUT_MODALITIES, which set a custom model's context, output and input limits.
New Contributors
- @tchopoorian made their first contribution in #3655
- @tahodev made their first contribution in #3771
- @linhongyu510 made their first contribution in #3689
- @DorZvulun made their first contribution in #3844
Contributors
Thanks to everyone who landed work in this release:
- versions: repin to hardened-2026-08-23 and let benign lock drift through by @gavrielc in #3496
- versions: repin the agent image to hardened-2026-08-24 by @amit-shafnir in #3531
- docs(add-opencode): document the OPENCODE_MODEL_* limit and modality env vars by @glifocat in #3524
- ci: handle branches without an old image pin by @glifocat in #3534
- fix(dial): post-merge follow-ups — credential re-run, step captions, registry CI by @glifocat in #3432
- feat(channels): add Mattermost installation skill by @glifocat in #3507
- fix(compose): inline every instruction source into one project document by @amit-shafnir in #3536
- Fix the blind agent-scope prompt by @OmriBenShoham in #3525
- fix(mattermost): improve initial setup and SiteURL handling by @glifocat in #3557
- fix(update): make the transaction controller correct on macOS hosts by @chiptoe-svg in #3506
- Install the Dial tool when the install has no agents yet by @OmriBenShoham in #3578
- fix(add-dial): add dial-status.test.ts to the nc:copy list by @OmriBenShoham in #3582
- fix(approvals): MPDM-aware approval cards via resolveConversation seam by @Koshkoshinsk in #3385
- fix(approvals): preserve adapter instance for DMs by @Koshkoshinsk in #3387
- fix(agent-runner): default task-run escalations to the agent's own channel by @Koshkoshinsk in #3388
- rollup: the durable host — coordination state, wake seam, reconcile queue, restart-honest delivery, claim fencing (#3508–#3528) by @gavrielc in #3653
- feat(db): durable host-coordination state and the seams that will consume it by @gavrielc in #3508
- fix(env): read quoted .env values the same way everywhere by @gavrielc in #3659
- fix(task-script): say a pre-task script timed out instead of "Command failed" by @gavrielc in #3662
- chore: use a neutral placeholder name in examples and fixtures by @gavrielc in #3663
- feat(config): install-wide default model and fast serving tier by @gavrielc in #3664
- feat(channels): let a chat-sdk channel recover content left in message.raw by @gavrielc in #3665
- fix(add-slack): copy slack-raw-text with the adapter that imports it by @gavrielc in #3667
- fix(ncl tasks): reject an empty --prompt on update by @tchopoorian in #3655
- test(skill-directives): expect the slack-raw-text pair in add-slack's copy fence by @glifocat in #3682
- chore(github): add issue forms by @glifocat in #3644
- docs(contributing): add the issue-side intake section by @glifocat in #3651
- ci(labels): automatic area/* from changed paths and kind/* from PR type by @glifocat in #3647
- feat(release): harvest PR release-note blocks into a draft changelog by @glifocat in #3650
- ci(labels): PR template v2 with token parsing and managed-kind reconcile by @glifocat in #3648
- ci(labels): report-only template-compliance status with a single fix comment by @glifocat in #3657
- feat(skills): the Slack agents companion skills move in-tree — main is canonical by @gavrielc in #3695
- chore(container): bump Bun and Claude runtimes by @omri-maya in #3698
- fix(supply-chain): activate the minimumReleaseAge gate (hoist out of
pnpm:key) by @sturdy4days in #2973 - fix(agent-runner): tell the agent send_card drops callback actions by @glifocat in #3427
- refactor(providers): render provider instructions from core-owned canon by @zvi-fried in #3591
- refactor(providers): declare the runtime provider contract by @zvi-fried in #3581
- refactor(providers): declare the host provider contract by @zvi-fried in #3585
- refactor(providers): render provider instructions from core-owned canon by @zvi-fried in #3727
- feat(groups): add a core-owned speed inference property by @zvi-fried in #3592
- refactor(providers): declare the setup provider contract and install verifier by @zvi-fried in #3586
- ci: add a gate job and a post-merge run on main by @gavrielc in #3736
- fix(db): stop the nested-continuation conformance test from racing its own watchdog by @gavrielc in #3737
- ci(registry-skills): a
registry gatecheck the ruleset can require, and a build that survives a Docker Hub 5xx by @gavrielc in #3739 - feat(setup): connect the host to its community cell and manage perks in the browser by @gavrielc in #3729
- fix(agent-runner): thread replies from the message being answered by @zvi-fried in #3738
- fix(setup): verify sees a nohup-started host when systemd has no user instance by @glifocat in #3760
- fix: recover uvx-installed pnpm after bootstrap by @tahodev in #3771
- fix(setup): print one portal link for the not-enrolled browser handoff by @Koshkoshinsk in #3754
- fix(setup): skip portal reminders the operator already answered by @Koshkoshinsk in #3758
- fix(setup): fetch explicit registry tracking refs by @glifocat in #3773
- fix(db): recheck migrations under SQLite write lock by @glifocat in #3766
- fix(setup): preserve files when registry copies fail by @glifocat in #3767
- fix(webhook): honor WEBHOOK_PORT from .env by @glifocat in #3770
- fix(setup): run downloaded installers with the system shell by absolute path by @glifocat in #3776
- fix(setup): start and verify the Linux fallback service by @glifocat in #3768
- fix: persist OneCLI gateway files across restarts by @glifocat in #3774
- fix(add-opencode): drop the pre-cli-tools Dockerfile guard on refresh and remove by @glifocat in #3763
- gateway providers: pass the session's container name in the provider input by @gavrielc in #3782
- fix(setup): restore the agent provider picker for fresh installs by @gavrielc in #3790
- fix: preserve provider cancellation, failure delivery, and skill files by @glifocat in #3746
- feat(add-opencode): implement provider contracts and host authentication by @glifocat in #3733
- feat(add-opencode): integrate setup and host assistance by @glifocat in #3747
- fix(setup): redact resolved secrets in skill execution logs by @glifocat in #3805
- fix(setup): commit related environment values atomically by @glifocat in #3806
- fix(mattermost): parse setup responses without jq by @glifocat in #3809
- fix(mattermost): connect to an operator-managed server by @glifocat in #3777
- fix(mattermost): validate and atomically persist selected settings by @glifocat in #3778
- fix(setup): verify the replacement host after restarting by @glifocat in #3779
- fix(mattermost): verify the running bot and server callback by @glifocat in #3780
- fix(update): snapshot symlinked mutable roots by @linhongyu510 in #3689
- Ignore .worktrees/ by @amit-shafnir in #3822
- feat(providers): declare default tone settings by @zvi-fried in #3826
- perf(cross-session-context): bound echo fan to the hot set, off the wake path by @gavrielc in #3829
- test(webhook): allocate free ports from the kernel instead of picking them at random by @gavrielc in #3830
- perf(host): reconcile and drain sessions concurrently; fixed-rate delivery polls by @gavrielc in #3832
- ci(registry-skills): bound the skill test jobs at 20 minutes by @glifocat in #3836
- fix(setup): enable corepack pnpm in ~/.local/bin when the global bin dir is read-only by @glifocat in #3847
- fix(setup): replace broken sudo retry with user-owned npm prefix fallback by @DorZvulun in #3844
- fix(setup): remember the image-source answer across resume so the Echo perk is offered once by @glifocat in #3861
- chore(add-codex): pin @openai/codex 0.155.1 by @amit-shafnir in #3867
- chore(container): bump Claude Code to 2.1.280 and the Agent SDK to 0.3.280 by @amit-shafnir in #3868
- fix(update): extract the whole scripts/ tree for the update controller by @tchopoorian in #3750
- refactor(gateway): centralize the credential gateway contract by @zvi-fried in #3815
- refactor(gateway): extract OneCLI into an installable skill by @zvi-fried in #3816
- feat(skills): add the Iron Proxy gateway by @zvi-fried in #3817
- feat(opencode): support authentication through Iron Proxy by @glifocat in #3825
- fix(update): stop this install's containers at cutover instead of waiting for them by @glifocat in #3873
- chore(release): v2.4.0 by @glifocat in #3877
Full Changelog: v2.3.0...v2.4.0
AI summary Slack agent upgrades and Codex version pinning changes
- [BREAKING] A new Slack experience — per-agent provisioned Slack apps, agent spawning from Slack, and UX improvements — is available to classic single-bot Slack installs. Classic Slack keeps working unchanged; this gate asks for a decision, not a forced migration. New installs and non-Slack installs are unaffected. Migration: run
/migrate-slack-agents— it detects classic state (exits cleanly otherwise) and either walks the upgrade or records the choice to stay on classic; both outcomes satisfy this requirement. /add-codexnow pins@openai/codex0.146.0. The previous pin (0.138.0) defaults to GPT-5.4, which OpenAI retires from Codex on 2026-08-31 — codex-provider agents ride the CLI default model, so stock installs stop completing turns at retirement — and it rejects the newer GPT-5.6 models with a 400 asking for a newer Codex CLI. Existing codex installs are not re-pinned by re-running/add-codex(the manifest merge is keyed on package name): edit the@openai/codexentry incontainer/cli-tools.jsonto0.146.0, rebuild the agent image (./container/build.sh), and restart.- [BREAKING] Agent mailbox access now goes through storage-neutral host and runner registries. The built-in SQLite implementation preserves existing session data and runtime behavior, but custom source may need to replace raw session-database access, await mailbox writes, update moved runner state/heartbeat helpers, drop
DeliveryActionHandler's database argument, use booleans fortrigger/onWake, and use the closed inbound-kind set. Migration: follow the agent mailbox seam migration guide for the complete detect grep, old→new symbol map, verification, and rollback. - Scheduled-task lifecycle semantics are stricter. Deleting an isolated task cascades its session state, updates refuse already-due runs, recurring selection uses the active series snapshot, and generated task timestamps retain millisecond precision.
- [BREAKING] The container runtime moves behind the session driver seam. Session containers are composed as a validated, admission-checked spec and realized by a selectable driver (
src/drivers/; Docker ships built-in and stays the default). Three surfaces break: (1) group folder names align to the runtime label grammar — at most 63 characters of[A-Za-z0-9_-], alphanumeric at both ends — so previously-legal 64-character names, trailing-/_, and unvalidated legacy imports refuse to spawn; (2) container names and invocation change fromnanoclaw-v2-<folder>-<timestamp>to key-derivedncl-…names (the old human-readable name survives as thenanoclaw-container-namelabel) and fromdocker runtocreate+start --attach— name-based tooling, Docker-command allowlists, wrappers, and audit rules should match by label instead (docker ps --filter label=nanoclaw-session, or--filter label=nanoclaw-group-folder=<folder>); (3) internal container helpers moved into the driver module — customized installs importinghostGatewayArgs,readonlyMountArgs,stopContainer,ensureContainerRuntimeRunning,cleanupOrphans, or patchingbuildContainerArgsstop compiling. Theuse-native-credential-proxyskill is retired: the spec's admission rules refuse credential values in container env on every lane, by design — credentials ride the OneCLI vault, and custom Anthropic endpoints use theANTHROPIC_BASE_URL+ placeholder-token pattern from setup. Migration: runbun scripts/detect-driver-migration.ts— it detects all three surfaces in your install and prints one finding per line with a minimal fix instruction; hand the output to your coding agent. Nothing detected means nothing to do. - Host restarts now adopt running sessions instead of restarting them. A service restart no longer kills in-flight agent work; to apply image or runtime changes to a group, restart it deliberately with
ncl groups restart. Pre-seam containers (spawned before this release) cannot be adopted and are removed at first upgraded startup, exactly as the old startup cleanup did. - Container gateway wiring is typed and admission-checked. The gateway's per-session contribution (proxy env, trust anchors, credential-stub mounts) merges into the session spec before validation instead of riding raw docker flags around it, and gateway selection becomes a registry (
NANOCLAW_GATEWAY_PROVIDER, defaultonecli— an install that never sets it behaves as it always has). - Non-root hosts get an explicit container identity. Every non-root host now passes
--user <uid>:<gid>andHOME=/home/node(previously uid-1000 hosts relied on the image'snodeuser). On uid-1000 systems whose primary gid is not 1000, files the agent writes into mounted workspaces now carry the host's gid — which is the intended behavior. CONTAINER_MEMORY_LIMITis validated at spawn. Invalid values refuse the spawn with a named error instead of surfacing as a raw Docker error; blank and0still mean uncapped.- An unknown
NANOCLAW_RUNTIME_DRIVERaborts startup (new variable — installs that never set it are unaffected), and drivers that cannot rebuild images in place denyinstall_packagesand--rebuildat request time instead of failing later. - [BREAKING] The host runtime now requires Node.js 22 or newer. Node 20 is not supported by the upgraded
better-sqlite3release used for current Node runtimes. Migration: runbash setup/install-node.sh, verifynode --versionreports v22 or newer, then rerun/update-nanoclaw; stay on the previous NanoClaw release if Node cannot yet be upgraded. - New NanoClaw installs now use OneCLI gateway 1.41.0. Existing 1.36.0 gateways remain compatible because NanoClaw does not depend on any 1.41-only behavior. See the OneCLI upgrade guide to upgrade an existing gateway.
- [BREAKING] Central database access is now asynchronous behind
DbDriver. SQLite remains the default and existingdata/v2.dbfiles are unchanged, but custom source and installed channel/provider extensions must await central reads and writes and adopt the retyped host seams. Migration: follow the central database async migration guide to find affected calls, preserve transaction boundaries, update extensions, verify SQLite behavior, or roll back. - Central DB composition and migrations are backend-ready. A one-slot driver registry keeps backend selection in
src/db/compose.ts;pnpm run migrateis the explicit schema-change path, host validation can fail closed without DDL, and a shared conformance suite pins transaction, parameter, ordering, and timestamp behavior. SQLite remains the installed default.
New Contributors
- @teran13 made their first contribution in #3230
- @brentkearney made their first contribution in #3210
Contributors
Thanks to everyone who landed work in this release:
- ci: let verify-agent-image run on every PR so it can gate by @gavrielc in #3238
- ci: open the agent-image bump PR from a dispatch by @gavrielc in #3240
- verify-agent-image: pin the publisher identity, and check attestations per arch by @gavrielc in #3158
- ci: let a verified signature be the approving review by @gavrielc in #3241
- verify-agent-image: arming auto-merge is not a verdict by @gavrielc in #3243
- fix(poll-loop): stopped loops leaked their active query's follow-up poller by @gavrielc in #3268
- engine: bump OneCLI gateway pin to 1.41.0 by @amit-shafnir in #3277
- Permissions: registerChannelCardInterceptor seam before registration cards (A4) by @gavrielc in #3266
- Agent-to-agent: CreateAgentOptions.suppressCreatedNotify (A3) by @gavrielc in #3265
- Delivery: registerDeliveryBatchPreview hook over each undelivered batch (A2) by @gavrielc in #3264
- Channel registry: hot-start a registered adapter after boot (A1) by @gavrielc in #3263
- channels: Chat SDK bridge agent-mode DM surface — app-context capture, DM-thread normalization, dm-opened hook (A8 + C4) by @gavrielc in #3262
- channels: optional adapter capabilities — status-bearing setTyping, setThreadTitle, setSuggestedPrompts + registry passthroughs by @gavrielc in #3261
- permissions: 'decline_notify' unknown-sender policy — polite decline + one-line owner FYI, no approval card by @gavrielc in #3260
- setup/tooling: skill-apply heading-ordinal strip, headless browser URL surfacing, inherit-script extraction by @gavrielc in #3259
- container: mid-turn streaming is the single delivery door — cross-segment assembly, DB-backed echo suppression, no result-door sends by @gavrielc in #3284
- Preserve structured chat links by @Koshkoshinsk in #3283
- fix: idle container with no heartbeat file is exempt from the absolute-ceiling kill forever by @gavrielc in #3252
- fix(skills): stop removal docs pointing at the retired data/env mirror by @teran13 in #3230
- docs(container): tell the agent where received attachments land by @brentkearney in #3210
- fix(container): bump pnpm and npm past fixable-critical tar CVE by @gabi-simons in #3207
- Add AnyDoc document conversion skill by @amit-shafnir in #3198
- Cross-session context for multi-session agent groups (batching, delivery-resolution, and detached-state prerequisites included) by @gavrielc in #3285
- channels: generic membership-event hook on the Chat SDK bridge by @gavrielc in #3295
- agent-runner: extendTool — additive MCP tool schema and description extension by @gavrielc in #3296
- delivery: post-delivery hook with first-delivery context by @gavrielc in #3294
- router: session-created hook for brand-new engaged sessions by @gavrielc in #3293
- setup: per-channel pre-step and companion-skill declarations for the wizard by @gavrielc in #3297
- channels: bridge inbound-policy registration seam by @gavrielc in #3292
- channels: adapter-declared session-mode context defaults (threads stamp derived) by @gavrielc in #3304
- fix(update): make NanoClaw upgrades transactional by @glifocat in #3195
- cross-session context: extend new-session backfill to group conversations by @gavrielc in #3312
- skills: channel welcome addenda, matched host-side (zero cost when absent) by @gavrielc in #3313
- setup: optional automatic Slack app provisioning behind an opt-in flag by @gavrielc in #3314
- Fix Telegram skill copy list by @Koshkoshinsk in #3316
- ci: add zvi-fried to core team roster by @gabi-simons in #3348
- drivers: a session-runtime driver seam, with Docker as the built-in realization by @gavrielc in #3306
- host: route session lifecycle through the driver seam by @gavrielc in #3307
- groups: refuse to create a group over a folder that already exists undisposed by @gavrielc in #3308
- refactor(db): prepare the central database for portable drivers by @moshe-nanoco in #3332
- refactor(db): add async central database seam by @moshe-nanoco in #3333
- [BREAKING] refactor(db): adopt async central database safely by @moshe-nanoco in #3334
- refactor(db): add backend composition and portable tests by @moshe-nanoco in #3335
- fix setup ping folder compatibility by @amit-shafnir in #3350
- docs(telegram): document approved group connection flow by @amit-shafnir in #3352
- setup: --slack-agents installs the whole Slack agents feature by @Koshkoshinsk in #3357
- fix(setup): fail closed when a stored sign-in cannot be verified by @gavrielc in #3339
- feat(setup): forward optional client metadata on Slack service requests by @gavrielc in #3345
- fix(approvals): record the delivering instance on pending_approvals by @gavrielc in #3340
- fix: support current Node runtimes by @Koshkoshinsk in #3360
- fix: expose decline notification overrides by @Koshkoshinsk in #3361
- feat(cli): accept bounded JSON from stdin by @zvi-fried in #3218
- fix(add-codex): bump @openai/codex pin 0.138.0 → 0.146.0 before GPT-5.4 retires from Codex (2026-08-31) by @chiptoe-svg in #3299
- Log a warning for unrecognized engage_mode instead of silent drop by @wakqasahmed in #3317
- feat: add agent mailbox seam and registry by @zvi-fried in #3349
- fix(setup): manage template agents after install by @amit-shafnir in #3365
- fix(setup): allow choosing a different Slack workspace by @Koshkoshinsk in #3383
- fix(permissions): disclose shared agent-group scope on approval cards by @Koshkoshinsk in #3386
- fix(setup): drop stale Slack experimental/public-URL copy, modal-agnostic app-creation walkthrough by @Koshkoshinsk in #3389
- feat(setup): finish Slack app installs the workspace must approve by @gavrielc in #3399
- setup: the managed Slack experience becomes the default by @gavrielc in #3404
- feat: add /migrate-slack-agents upgrade path for classic Slack installs by @Koshkoshinsk in #3391
- fix(permissions): assert the scope warning via its constant, not a copy of it by @gavrielc in #3407
- docs+setup: announce one-click Slack agents by @gavrielc in #3421
- feat(drivers): ratify the attach surface — a driver describes its exec argv by @gavrielc in #3429
- fix: restore stable CI required check by @zvi-fried in #3430
- [main] fix(providers): accept provider file events by @zvi-fried in #3402
- [main] fix(matrix): use a refresh-safe ESM patch by @zvi-fried in #3403
- [main] ci: test registry-backed skills by @zvi-fried in #3424
- feat(setup): add Dial to the channel picker + wizard/skills (runChannelSkill model) by @OmriBenShoham in #3050
- chore(container): bump claude-code to 2.1.238 and agent SDK to 0.3.238 by @gavrielc in #3439
- fix(add-dial-number): use nc directives by @zvi-fried in #3433
- feat(drivers): validate runtimeTier against driver isolation capabilities; select the tier from group config by @gavrielc in #3442
- fix(upgrade-state): accept a version-matching marker when Git cannot identify the checkout by @gavrielc in #3444
- build: drop better-sqlite3 from onlyBuiltDependencies — use its bundled prebuilds by @gavrielc in #3443
- fix(setup): skip Slack auto-provisioning when a bot is already saved by @Koshkoshinsk in #3390
- fix(telegram-setup): pairing card says 6 digits by @amit-shafnir in #3431
- fix(chat-sdk): polling adapters do not open the webhook server by @amit-shafnir in #3434
- feat(setup): carry the adapter instance through pairing, init-first-agent and the CLI welcome by @amit-shafnir in #3478
- docs(add-telegram): add-another-bot path, instance-aware pairing and wiring by @amit-shafnir in #3479
- feat(setup): the wizard offers "add another Telegram bot" when one is already configured by @amit-shafnir in #3480
- chore(release): v2.3.0 by @gavrielc in #3495
Full Changelog: v2.2.0...v2.3.0
AI summary **Breaking changes to agent templates and plugin updates**
- Stamped plugins update in place through
ncl groups create --template <ref>. When a group already carries the template's plugin, the same command becomes an in-place update instead of minting a duplicate agent: a dry run prints a plan of every plugin-owned surface (plugin files, skills, MCP servers, persona, context files, tasks), flagging locally customized files whose edits would be lost;--yesapplies,--idpicks among several stamped groups,--newdeliberately stamps another agent. Agent state the plugin does not own (memory,plugin-data/, user-added MCP servers, task pause/resume state, wiring) is never touched. Plugin-stamped MCP servers now carry an ownership marker and refuse direct edits viancl groups config add-mcp-server/remove-mcp-serveror the agent'sadd_mcp_servertool: update the plugin and restamp instead. - [BREAKING] Agent templates are now Agent Plugins 1.0.0 directories.
plugin.jsonreplacescontext/instructions.mdas the required file; MCP servers move to a spec-shapedmcp.json; persona, extra context, and tasks move under theai.nanoco.nanoclaw/extension dir. Templates become portable to other plugin clients, and any conformant third-party plugin stamps as a NanoClaw agent. Migration: re-fetch templates from the registry (the pre-plugin layout fails with a migration error); to convert a local custom template, see docs/templates.md. - Plugin MCP servers may declare a working directory.
cwdinmcp.json(fixed forms./p,${PLUGIN_ROOT}[/p],${PLUGIN_DATA}[/p]) now launches the server in that directory instead of being skipped: resolved to an absolute container path at runtime, consumed natively by providers that support it and via acd-then-execlaunch shim on Claude. A stdio server that omitscwdruns from the plugin root (the spec default). - Setup can stamp the first agent from a template. The wizard offers the NanoClaw template library (or local
templates/) when creating the first agent;--template-path <ref>or the advanced screen presets the pick. A rerun over a partial install updates the stamped agent in place (dry-run plan + confirm) instead of duplicating it, the pick persists across wizard re-execs and reruns, and a template failure warns and continues instead of aborting setup. - Remote MCP servers can use Streamable HTTP. Register them with
ncl groups config add-mcp-server --name <name> --url <url>or the existing admin-approvedadd_mcp_servertool. Local stdio MCP commands keep their currentcommand/args/envbehavior; remote credentials remain OneCLI-managed: URLs with userinfo, fragments, or credential-looking query parameters are rejected. HTTPS is required except forlocalhost/host.docker.internal. - [BREAKING] Host modules now use one lifecycle registry. Custom modules that import
onShutdown()orgetShutdownCallbacks()fromresponse-registry.tsmust move to the host lifecycle API. Migration: follow the host lifecycle migration guide to detect affected code, update it, verify the cutover, or roll back. - Agent-to-agent messaging no longer loses to Claude Code's built-in
SendMessage. That built-in addresses the SDK's own in-session subagents, so an agent that had just runcreate_agentreached for it by name and gotNo agent named 'x' is currently addressable— reading as "the group was never provisioned" whilemcp__nanoclaw__send_message(the real path) was never called.SendMessagejoinsAskUserQuestioninSDK_DISALLOWED_TOOLS, so the PreToolUse hook now blocks it and points at the nanoclaw equivalent. - [BREAKING] Existing Claude installs should review the hardened agent image. Local builds remain supported, but the Echo-built image is recommended for patched sandbox components. Migration: follow the hardened-image guide to detect your current image source, switch, verify, or roll back.
- Release publication tolerates GitHub API propagation. The Release workflow now retries bounded post-publication read-backs when the new Release is not listed yet or its immutable state is not visible yet. Exact title, body, tag, or SHA mismatches still fail immediately.
- The
add-tavily-toolskill adds Tavily Search and Extract as keyless remote MCP tools for selected agent groups, bridged through a pinnedmcp-remote. - Scheduled tasks now run with their effective scheduled occurrence as the task time, plus a task-only
current_time(weekday included, in the agent group's timezone) instead of the creation timestamp. - Accumulated messages stay available as context without spuriously triggering warm-container follow-up turns; group-scoped agents can inspect their wirings and request approved engagement-policy updates; invalid engagement regexes are rejected.
- Hosted iMessage setup now provisions the line's user row directly and prints the assigned number to text once; that first message is the opt-in the delivery plane checks, and re-runs reuse the existing row.
- Resolved approval cards keep their title and request details, replace buttons with the decision and actor (or a timeout status), and survive host restarts and delayed resolution.
- Setup failure assist now offers diagnosis through the provider the operator picked instead of always offering to install Claude.
ensureUserDmgains an opt-in privacy-safe logging mode for security-sensitive flows: user IDs, handles, messaging-group IDs, and raw adapter errors are omitted while non-identifying channel context is kept.- The stale
add-gcal-tool,add-gmail-tool, andget-qodo-rulesskills were removed. - The recommended hardened agent image is repinned to
hardened-2026-08-13. - The package description now says personal AI assistant: NanoClaw is provider-agnostic, not Claude-only.
- Docs: skills define a single-responsibility integration rule, and the hardened-image guide states that
install_packagescovers apt and npm packages only.
New Contributors
- @dim0627 made their first contribution in #3187
- @zvi-fried made their first contribution in #3211
- @stumpjumper made their first contribution in #3216
- @manisrinivasan2k1 made their first contribution in #3190
Contributors
Thanks to everyone who landed work in this release:
- fix(setup): dispatch failure assist to the picked provider by @glifocat in #3170
- fix(release): retry post-publish readback by @glifocat in #3176
- Preserve resolved approval card content by @Koshkoshinsk in #3143
- fix(imessage): opt in via first message to the assigned line by @glifocat in #3181
- Fix engagement consistency and expose self-serve wiring controls by @Koshkoshinsk in #3137
- fix(update): surface hardened image migration by @gabi-simons in #3180
- versions: repin the agent image to hardened-2026-08-02 by @gavrielc in #3182
- fix(agent-runner): give scheduled tasks current run time by @Koshkoshinsk in #3154
- fix(agent-runner): disallow built-in SendMessage so agent-to-agent messaging works by @dim0627 in #3187
- chore(skills): remove stale qodo and Google MCP skills by @glifocat in #3172
- docs(skills): define single-responsibility integration rule by @zvi-fried in #3211
- refactor(db): add module migration registry by @zvi-fried in #3212
- refactor(host): unify module lifecycle hooks by @zvi-fried in #3214
- refactor(channels): register question renderers by @zvi-fried in #3213
- feat(permissions): add opt-in privacy-safe DM logs by @zvi-fried in #3222
- docs(hardened-image): note that install_packages covers apt and npm only by @stumpjumper in #3216
- feat: support remote Streamable HTTP MCP servers by @amit-shafnir in #3092
- feat: add Tavily MCP tool skill by @manisrinivasan2k1 in #3190
- feat!: agent templates become Agent Plugins 1.0.0 directories by @amit-shafnir in #3220
- feat(setup): template setup flow in the wizard and first-agent stamping by @amit-shafnir in #2909
- versions: repin the agent image to hardened-2026-08-13 by @gavrielc in #3236
- chore(release): v2.2.0 by @glifocat in #3237
Full Changelog: v2.1.54...v2.2.0
Rollup release covering v2.1.18 through v2.1.54 — everything merged since the v2.1.17 tag.
- [BREAKING] iMessage unified into one
imessagechannel with two backends via/add-imessage: Local (this Mac'schat.dbvia the Chat SDK) or Hosted (native Photon viaspectrum-ts, no Mac relay). Backend chosen at install or viaIMESSAGE_BACKEND=local|hosted. The legacy Chat-SDK remote mode (IMESSAGE_SERVER_URL/IMESSAGE_API_KEY) and the separateimessage-cloudchannel +/add-imessage-cloudskill are removed. See docs/imessage.md. - [BREAKING] Provider-agnostic memory. All providers now share one OKF v0.1-compatible
memory/tree, while persona lives ininstructions.prepend.md; startup, clear, and compact reload memory automatically. Existing groups with legacy memory must run/migrate-memorybefore use. See memory and provider migration. - New groups can inherit an instance-wide default provider.
DEFAULT_AGENT_PROVIDERsets the provider used when a new agent group is created without an explicit provider. Each group's stored provider still overrides it, and existing groups are unchanged. - [BREAKING] Channel install skills are now the single source of truth. The setup wizard installs channels by applying the same
/add-<channel>SKILL.md a coding agent would follow — a deterministic engine executes the skill's mechanical steps directly from the document, so wizard and skill cannot drift, and anything the engine cannot do falls back to an agent reading the prose. Migration: the bespoke non-interactive channel installers (setup/add-<channel>.sh,setup/install-<channel>.sh) and per-channel wizard flows (setup/channels/<channel>.ts) are deleted. Anything that invoked them should apply the skill instead: interactively via/add-<channel>or the setup wizard, or programmatically via skill directives. - One guard for privileged actions. Every privileged action crossing the container or channel boundary now passes through
guard()before execution:allow,hold, ordeny. Approved replays carry the approval row as a grant and re-run checks against current state; forged, consumed, mismatched, or newly unauthorized grants fail closed. Guarded delivery actions can no longer be re-registered without their guard specification. - [BREAKING]
whatsapp-formattingandslack-formattingmoved from trunk to thechannelsbranch. They now install with their channel, so installations without those channels no longer carry channel-specific formatting instructions in every agent's context. Migration — only if the channel is installed: re-run/add-whatsappor/add-slackafter updating. Do not run an add-skill preemptively; it installs the full adapter. - [BREAKING] Scheduled tasks moved from MCP tools to
ncl tasks. Agents and operators now manage tasks withncl tasks list/get/create/update/cancel/pause/resume/delete/run/append-log; task sessions are isolated from the chat session that created them. Migration: follow the scheduled-task migration guide. - [BREAKING] Task delivery is explicit and uses one door. Every
send_messageandsend_filecall requires a namedtodestination; task-session final output becomes the run summary, while only explicitly addressed tool calls deliver. Migration: rebuild the agent image, restart NanoClaw, update custom instructions that omitto, and clear or compact existing sessions. Failed pre-task scripts now back their recurring series off and auto-pause after eight consecutive failures instead of spinning. - [BREAKING] Chat SDK and channel adapters are pinned to
4.29.0. The bridge and adapter must use the sameChatInstancetype, so exact pins replace caret ranges. Core installations without a channel are unaffected. Migration: if a channel is installed, re-run its/add-<channel>skill after updating. - Hardened agent images are available as an opt-in setup path. A digest-pinned, multi-architecture image can be fetched from the NanoClaw registry and retagged to the same local name used by builds; architecture, lockfile, provenance, size, and optional publisher-signature checks fail closed. Local builds remain the default and require no account. See hardened images.
- Agent containers now start with safer defaults. New spawns always drop all Linux capabilities, set
no-new-privileges, and use Docker's init process; these controls have no per-group override. A PID limit defaults to 2048 and can be changed installation-wide withCONTAINER_PIDS_LIMIT(0disables it). The Vercel CLI is now opt-in instead of being baked into every image. - Agent containers can have installation-wide resource caps.
CONTAINER_CPU_LIMITandCONTAINER_MEMORY_LIMITpass--cpusand--memoryto Docker for every agent container. Both remain empty by default, so existing installations keep their current behavior. - Per-agent-group timezones.
ncl groups config update --timezone <IANA>overrides the install timezone for that group's scheduling, run-log display, and containerTZ;""clears the override. Host-side operator display remains in the install timezone. - Agent templates and reusable skills expanded. Local templates can stamp persona, context, MCP configuration, and skills through
ncl groups create --template; templates can also seed scheduled tasks and timezone./learndistills a reusable skill from an existing workflow, and/add-clidashinstalls a read-only CLI-derived dashboard. - A clearer, safer
nclcontrol plane. Verbs now declare and validate their arguments, generate deep help, preserve dashed IDs, render human-readable output on the host, and flush large responses before exit. Creating groups and wirings now provisions their required companion rows transactionally, fixing first-spawn failures and silently dropped replies. - Approval and agent-to-agent controls are more expressive. Connected agents can require per-message approval; rejection reasons reach the requester; OneCLI approval cards use the gateway's structured summary; and shared-channel cards retain who approved or rejected an action.
- Delivery and provider failures stop disappearing. Missing adapters route messages into retry instead of marking them delivered, agent image builds no longer block the host, and Claude rate-limit telemetry only aborts a turn when the SDK reports a rejection. Billing exhaustion and transient rate limits remain distinct.
- Setup and update recovery improved. Setup can parse wrapped Claude OAuth captures, offer Slack Socket Mode, and reap dead peer-service registrations. Re-applying an updated skill rebuilds the container when needed, and a missing session folder is re-provisioned so the documented reset path works.
- Security fixes. Inbox attachment writes reject symlink escapes, approved CLI calls preserve the original caller context, command-gate checks no longer fail open, mount allowlists honor
readOnly, and stale v1 secret/config mirrors were removed. - Documentation was refreshed across architecture, database schemas, security boundaries, provider configuration, SDK behavior, skills, and registry-branch maintenance. A Korean README is now available.
New Contributors
- @arkjun made their first contribution in #2806
- @sturdy4days made their first contribution in #2803
- @moshe-nanoco made their first contribution in #2793
- @cben0ist made their first contribution in #2859
- @johnmathews made their first contribution in #2880
- @thisdotrob made their first contribution in #2885
- @leetwito made their first contribution in #2795
- @Shufel83 made their first contribution in #3003
- @boazdori made their first contribution in #2748
Contributors
Thanks to everyone who landed work in this release:
- fix(setup): parse Claude OAuth token from wrapped PTY capture by @amit-shafnir in #2805
- docs: add Korean README by @arkjun in #2806
- refactor: remove dead resolveGroupIpcPath by @sturdy4days in #2803
- refactor: mirror .claude skills + CLAUDE.md into .agents via symlinks by @Koshkoshinsk in #2810
- feat(agent-to-agent): per-message approval policies on connected agents by @moshe-nanoco in #2793
- fix(setup): allow env-selected agent provider by @amit-shafnir in #2811
- chore(deps): move chat SDK + channel-adapter pins to 4.29.0 by @gabi-simons in #2834
- fix(update-skills): nudge into skill updates, rebuild container on re-apply by @Koshkoshinsk in #2826
- fix(setup): reap dead peer service registrations whose binary is gone by @amit-shafnir in #2830
- feat(container): per-container CPU/memory limits (opt-in) by @omri-maya in #2856
- feat: add /learn skill — distill or refine a reusable skill from anything by @robbyczgw-cla in #2843
- feat(approvals): reject with reason by @moshe-nanoco in #2832
- fix(migrate-v2): don't SELECT is_main from v1 registered_groups by @cben0ist in #2859
- fix(ncl): default messaging-groups create instance to channel_type by @omri-maya in #2882
- fix(security): contain inbox symlink escapes in attachment writes (#2828) by @johnmathews in #2880
- fix(setup): offer Slack Socket Mode in the guided setup flow by @thisdotrob in #2885
- feat(templates): local template loader, ncl --template, and docs by @amit-shafnir in #2890
- [security] fix(cli): preserve caller context after approval by @Hinotoi-agent in #2611
- Unregister the mock provider from the production container barrel by @gavrielc in #2927
- Remove the dead /workspace/global mount and untrack v1 group seed files by @gavrielc in #2928
- feat(approvals): render OneCLI approval requests from the gateway's structured summary by @gavrielc in #2929
- command-gate: restore the /start filter and remove the fail-open admin check by @gavrielc in #2930
- Fix ncl positional IDs for generated (dashed) identifiers by @gavrielc in #2932
- feat: add /add-clidash — read-only CLI-derived dashboard skill by @leetwito in #2795
- feat(approvals): colored buttons on approval cards (Slack primary/danger) by @gavrielc in #2933
- Make the security-perimeter env vars reachable under the shipped service by @gavrielc in #2934
- Delete dead v1 config knobs and the broken pnpm auth script by @gavrielc in #2935
- Clean up dead ncl CLI protocol vocabulary by @gavrielc in #2936
- Re-provision a missing session folder so the documented reset works by @gavrielc in #2937
- Delete one-DB-era @deprecated shims and dead exports by @gavrielc in #2940
- Fix the agent-to-agent in_reply_to stamp (cross-process no-op) by @gavrielc in #2942
- Mount allowlist: honor the readOnly key and stop caching parse errors by @gavrielc in #2943
- Rewrite the security docs to match the v2 perimeter by @gavrielc in #2945
- Remove the dead data/env/env secrets mirror by @gavrielc in #2946
- Fix stale architecture, scheduling, provider-config, and overlay docs by @gavrielc in #2948
- Build agent images asynchronously instead of blocking the host by @gavrielc in #2931
- docs: correct stale mount topology row + removed env var by @glifocat in #2953
- docs: fix stale claims across README, CONTRIBUTING, CLAUDE.md and operational docs by @glifocat in #2961
- docs: sync DB schema and entity docs with migrations 010-018 by @glifocat in #2962
- docs: rewrite architecture.md and agent-runner-details.md to match current code by @glifocat in #2963
- docs: update SDK deep-dive from 0.2.x to 0.3.197 by @glifocat in #2964
- fix(agent-runner): match rate_limit_event as a top-level SDK message type by @glifocat in #2965
- Wizard UX + add-slack Socket Mode fixes by @Koshkoshinsk in #2972
- ncl CLI: verb-level args, deep help, server-rendered human view by @omri-maya in #2980
- ci: auto-label PRs from core team members by @gabi-simons in #2978
- Scheduled tasks: ncl tasks control plane, isolated sessions, script gate by @omri-maya in #2981
- fix(cli): provision companion rows on
ncl groups createandncl wirings createby @glifocat in #2416 - fix: stamp task rows with ISO timestamps by @gavrielc in #3005
- fix: ISO storage + local-time display for all timestamps by @gavrielc in #3006
- docs(agent-browser): require bounded waits for custom conditions by @Shufel83 in #3003
- Move channel formatting skills (whatsapp, slack) from trunk to the channels branch by @gavrielc in #3009
- feat: adapter-declared channel defaults (engage mode, threading, sender policy) by @gavrielc in #3010
- add-teams: Teams-CLI-first credentials flow in SSF directive grammar by @Koshkoshinsk in #2958
- Warn before connecting a shared WhatsApp number by @Koshkoshinsk in #3021
- Guard seam: one decision function for every privileged action (guarded-actions phase 2) by @moshe-nanoco in #2986
- feat: lean harness defaults for new agent groups by @gabi-simons in #3031
- Tasks: one-door delivery — send_message is the only path out of a task session by @omri-maya in #2988
- fix(agent-runner): log when an errored batch is acked completed by @glifocat in #2966
- fix(delivery): route missing-adapter messages into the retry path by @glifocat in #2996
- fix(container): warn when a real entry blocks a shared skill symlink by @glifocat in #3002
- Structured skill format: setup installs channels by applying the SKILL.md by @gavrielc in #3035
- feat: instance-wide default agent provider for new groups by @Koshkoshinsk in #2906
- fix(self-mod): render full MCP server payload on the approval card by @glifocat in #2998
- feat: support scheduled tasks in templates by @amit-shafnir in #3022
- fix(skills): switch Telegram deep-link from t.me to telegram.me by @amit-shafnir in #3043
- feat(memory): add provider-agnostic persistent memory by @amit-shafnir in #3012
- docs(add-whatsapp-cloud): document webhook route + state-namespace migration for instance key by @glifocat in #2914
- docs(changelog): drop duplicated Unreleased bullets by @glifocat in #3063
- fix(agent-runner): compact_boundary must not surface as a result by @gavrielc in #3083
- test(runner): drop temporary diagnostics from the /clear-abort test by @gavrielc in #3084
- fix(claude): only abort on a rejected rate_limit_event; split rate_limit vs quota by @javexed in #3077
- docs: rewrite branch maintenance guide for the registry-branch model by @glifocat in #3095
- security: harden agent containers (cap-drop, no-new-privileges, pids-limit) by @boazdori in #2748
- feat: per-agent-group timezone override by @Koshkoshinsk in #3125
- setup: fetch a hardened agent image instead of building it by @gavrielc in #3150
- container: make the Vercel CLI opt-in rather than baked into every image by @gavrielc in #3159
- versions: repin the agent image to hardened-2026-07-30 by @gavrielc in #3160
- fix(release): restore the v2.1.54 release path by @glifocat in #3163
- Hosted iMessage (Photon): supersede #2999 with a working registration flow by @glifocat in #3164
- fix(release): close post-merge safety gaps by @glifocat in #3168
Full Changelog: v2.1.17...v2.1.54
@ Every self-hosted release, weekly
One Monday email with the week's stable releases across the directory.
FAQ
Is NanoClaw open source?
Yes, fully open source under MIT, with the whole codebase on GitHub and forking/customization actively encouraged.
How does NanoClaw compare to other AI agent frameworks?
It targets people who want an assistant they own and control: one Node.js host coordinating isolated per-session Docker containers, Claude by default, with Codex, OpenCode or local Ollama configurable per agent group.
How do I set up and configure NanoClaw?
Clone the repository and run bash nanoclaw.sh, which prepares Docker and the credential vault, asks which provider powers the first agent, and pairs a channel. Later changes are applied through repository skills.
Can I run NanoClaw on Linux or Windows?
Yes; on Windows it runs inside WSL2. You bring git and a provider credential, and the script installs Node.js, pnpm, Docker and OneCLI when missing.
What container runtimes are supported?
Docker only, on macOS, Linux and Windows through WSL2.
What messaging apps does NanoClaw support?
A long list including WhatsApp, Telegram, Discord, Slack, Teams, Signal, iMessage, Matrix, Mattermost, Google Chat and email via Resend; each adapter is installed on demand with a skill.
Is NanoClaw free?
The software is free under MIT; you only pay your model provider. Claude takes an API key or a subscription, Codex a ChatGPT subscription or OpenAI key, and local Ollama models avoid hosted-model bills.
Do I need to know how to code to use NanoClaw?
No - the installer handles dependencies, credentials, containers and channel pairing, though comfort with a terminal and git clone is expected.
Is NanoClaw secure?
Each session runs in its own unprivileged container and only sees the files you mount; credentials stay in the gateway. Egress lockdown, mount rules, sender policies and approvals narrow it further.
How is NanoClaw different from OpenClaw?
NanoClaw keeps a single Node.js host process with an auditable codebase and puts every active session behind OS-level container isolation, with channels and providers installed as skills.
What is NanoClaw?
A lightweight open-source personal AI agent that runs on your own machine, connects to the messaging apps you pick, and executes each session inside an isolated Docker container.
More in AI Assistant
nekoniNekoni is a self-hosted, open-source AI agent running locally via Ollama with P2P WebRTC phone access, RAG, skills automation, and Ed25519 auth.
NeoAgentNeoAgent is a self-hosted, open-source AI agent with persistent memory, scheduled automation, live browser and device control, and 24 messaging channels under AGPL-3.0.
NextClawSelf-hosted AI assistant you run on your hardware. Links to many model providers and chat platforms, preserves context, runs background jobs with an inbox.
nextcloud-mcp-serverA self-hosted, open-source MCP server that lets AI assistants interact with your Nextcloud instance — managing notes, calendars, contacts, files, and more.
nextgptNextGPT is a self-hosted AI chatbot with document processing, RAG search, and web search. Deploys via Docker Compose or to AWS/GCP.
nexus4ccSelf-hosted web terminal bridging browsers to tmux sessions running Claude Code and other AI agents, with project/channel management, file browser, and PWA support.
novaSelf-hosted personal AI with a measured memory loop and 70+ autonomous monitors building living dossiers — all local, zero cloud.
OfferPilotOfferPilot is a self-hosted, open-source job search workspace to track applications, manage resumes, practice interviews with AI, and compare offers.
OgcodeSelf-hosted, open-source AI coding agent that maps codebases, recalls decisions across sessions, and runs locally with any model provider including Ollama.
OllamaUIOllama UI is a self-hosted, open-source web interface for exploring, pulling, and managing Ollama models with chat, tool calling, and Telegram bridge.
Omada-mcpSelf-hosted MCP server giving AI assistants secure, capability-gated access to TP-Link Omada Controller APIs for network automation.
OmniOmni is a self-hosted, open-source AI agent connecting to workplace tools like Google Workspace, Microsoft 365, Slack, and Jira to gather context and execute tasks.



0 comments