NanoClaw v2 — installation and isolation

Reviewed: 10/10/2026
Project: https://github.com/nanocoai/nanoclaw
Isolation model: https://github.com/nanocoai/nanoclaw/blob/main/docs/isolation-model.md

This guide corresponds to NanoClaw v2, according to the documentation reviewed on 10/10/2026. The installation uses bash nanoclaw.sh; v1 has a different data and configuration schema. Check the deployed commit before applying instructions from main.

1. Features

NanoClaw is a self-hostable assistant that runs agents in Linux containers with explicitly allocated resources. The Node host receives messages and orchestrates containers; the runner uses Bun and, by default, Claude Agent SDK. It allows conversations, memory and permissions to be separated by work scope. Channels and providers are added via skills to the fork.

Features documented in v2

• Multi-channel messaging: Telegram, Slack, Discord, WhatsApp, iMessage and others via skill-based installation (not all included in main).
• One agent can use several channels and vice versa, with shared or separate sessions.
• Agent groups with their own identity, memory, instructions and file system.
• Docker on macOS/Linux/WSL2; one host orchestrates separate containers.
• Scheduled tasks, web browsing, tools, agent templates.
• Credentials gateway: keys do not enter the container as raw values; they are injected into permitted outbound requests.
• Main model Claude Agent SDK, with alternatives installable via skills: Codex, OpenCode and Ollama, according to current documentation.
• "Code + skills" customization instead of large configuration panels.

2. NanoClaw v2 architecture

Telegram / Discord / Slack / WhatsApp / etc.
                     |
              ADAPTADORES host
                     |
             Node host / router
                     |
             DB central (v2.db)
                     |
       DB por sesión: inbound.db  <-- host escribe, contenedor lee
                     |
          Contenedor del agente
        Bun + SDK + herramientas
                     |
       DB por sesión: outbound.db <-- contenedor escribe, host lee
                     |
           host entrega respuesta

             Salidas a APIs
                     |
       Credential gateway / Vault
                     |
         Servicios autenticados

According to the official migration and architecture notes:

• data/v2.db stores users, roles, agent groups, message groups and relationships.
• data/v2-sessions/<session_id>/inbound.db receives messages/events/tasks; primary writer: host.
• data/v2-sessions/<session_id>/outbound.db accumulates responses/state; primary writer: container.
• groups/<folder>/ contains identity/instructions/memory and agent group configuration.
• groups/<folder>/container.json is optional container and mount configuration. Do not copy v1 recipes without reviewing the current format.
• The host performs periodic sweeps and wakes containers when there are messages or tasks.
• Channel and provider extensions are registered when their skills are installed; main contains mainly infrastructure.

The host controls input and output; the container runs the agent. Both are part of the trust model.

3. Isolation levels

NanoClaw distinguishes communication channel, agent group and session. Not all multi-chat configurations represent privacy between users.

Level 1 — Shared session (agent-shared)

Two or more channels write to the same conversation. They share workspace, memory, instructions and history; even messages from different platforms appear in the same context.

Suitable: GitHub alerts and a Slack for the same project that deliberately want a joint conversation.
Unsuitable: personal life vs work, external users with non-equivalent access.

Level 2 — Same agent, independent sessions (shared / per-thread)

Chats keep separate threads, but share durable memory, tools, files and agent group identity. One conversation does not appear verbatim in the other, but indirect leakage through persistent memory may exist.

Suitable: a user who uses the assistant from Telegram and Discord.
Unsuitable: different people with mutually confidential information.

Level 3 — Separate agent groupsEach scope has a different agent group, with different container, memory, workspace, instructions and sessions. The recommended option if there are real boundaries between clients, team members, personal and work data.

Suitable: one personal bot and another work bot; several clients/users with different access. Nuance: even if they are separated at the application and filesystem level, the host, the Docker daemon, the credentials gateway and the operating system are still shared infrastructure. For mutually hostile adversaries, consider separate VPSs/VMs.

Choice table

Reference: https://github.com/nanocoai/nanoclaw/blob/main/docs/isolation-model.md

4. Requirements

Official v2 documentation:

• Linux or macOS, Windows via WSL2.
• Node.js 22+ and pnpm 10+ (the current script can install them if missing).
• Docker Engine on Linux or Docker Desktop on macOS/Windows.
• Claude Code for guided customizations, installation of channel skills and recovery from setup errors.
• A credential or subscription compatible with the selected provider. Anthropic is used by default; other providers need their appropriate integration.
• Outbound network and resources for Docker, the host, the containers and the credentials gateway.

Hardware: starting proposal, not an official requirement

For a test with remote models and few conversations, start from 2–4 vCPU, 4 GB RAM and 30 GB SSD and measure consumption. This is a deployment estimate, not an official minimum. Adjust concurrency and container limits according to the host resources and the configuration of the installed version.

5. Installing v2 on Linux (main path)

5.1 Prepare the environment

Reference preparation for Ubuntu/Debian; review the changes before applying them:

sudo apt update
sudo apt install -y git curl ca-certificates
# Instala Docker Engine/Compose y verifica que el daemon es operativo.
docker version
docker info
node --version     # objetivo >=22
pnpm --version     # objetivo >=10

Docker security: being a member of the docker group confers practically host administrator privileges on a rootful daemon. Therefore you should not treat an account with access to the Docker socket as an "isolated service user". Use a VPS dedicated to the experiment or a trusted administrator. Never provide /var/run/docker.sock as an agent volume.

5.2 Clone and record the version

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
git rev-parse HEAD
# Guarda ese SHA en tu inventario de infraestructura.

Review nanoclaw.sh, setup files, Dockerfile, credentials policy and skills to be installed, especially if it is a machine with personal data. The setup script can install system components and, if it fails, delegate diagnosis/repair to Claude Code; it should not be run blindly on a sensitive production host.

5.3 Run the official onboarding

bash nanoclaw.sh

The README states that the current wizard installs/prepares Node, pnpm and Docker if missing, configures a credentials gateway, registers the Anthropic credential, builds the container and pairs the first channel: Slack, Telegram, Discord, WhatsApp, iMessage or local CLI, depending on the environment. It can invoke Claude Code automatically if there are failures. Read the operations it proposes and use low-privilege test credentials.

Suggested flow for a headless VPS:

1. Choose local CLI or Telegram as the first channel; minimize integrations until isolation is verified.
2. Explicitly declare which user is the owner, who can administer it and what the policy is for unknown senders.
3. Create a single test agent with an empty workspace.
4. Verify that the response comes from the container and that the credential is used through the gateway.
5. Only then add more channels and groups.

Consult the installed version's help for service names and configuration options.

6. Connecting Telegram and other channelsIn v2, integrations are added via skills. The README indicates /add-telegram, /add-discord, /add-opencode, etc.; commands with / run inside the Claude Code prompt, not directly in bash.

Telegram Example

1. Create a bot with @BotFather.

2. In your v2 checkout, open Claude Code:

   cd nanoclaw-v2
   claude
   

3. Inside Claude Code, request the skill:

   /add-telegram
   

4. Follow the specific flow: channel registration, token, owner, linking with the agent group, and policy for unknown senders.

5. Test messages from your account and from a second unauthorized account.

6. Verify that untrusted messages do not receive administrative permissions by mentioning a keyword.

If you have already paired Telegram during bash nanoclaw.sh, do not repeat the channel installation without reason. Check the status of your installation and the skill documentation.

Extra Channels

The repo cites, among others, Slack, Discord, WhatsApp, iMessage, Microsoft Teams, Matrix, Google Chat, Webex, Linear, and GitHub. The list does not mean all of them are preinstalled. Skills add modules from the channels branch and specific dependencies to the fork. Before granting permissions to Slack/GitHub/Gmail, create credentials with minimal scopes and test revocation.

7. Credentials Gateway and Policies

Why It Matters

In v2, the README presents a credential gateway that injects secrets into outbound traffic without giving the raw key to the container. During setup, one of the supported gateways is installed—the README currently mentions OneCLI Agent Vault—; per-agent rules and rate controls can be applied.

Verify that keys are not mounted or included as container variables; isolation depends on that configuration.

Critical Limit: Default Secret Mode

The v1→v2 notes indicate that automatically created agents may start in a all secrets mode, which allows automatic injection of secrets whose host patterns match. For strong separation, review and switch to selective mode according to the interface and help of the installed OneCLI version; the reference mentions onecli agents set-secret-mode --mode selective as a command family. Run:

onecli agents --help
onecli agents set-secret-mode --help

The specific syntax for identifying an agent depends on the release. Do not apply an incomplete command to the wrong target. Add allowlist rules per host/API/agent and limit spending per credential at the provider.

Never put tokens in: messages, files visible to all agent groups, shared instructions, Docker image, or Git repository. Keep the host process, OneCLI volumes, and Docker account under administrator control.

Data and Diagnostics

According to the README, the product does not require its own account for basic functionality and reports anonymous setup diagnostics. If you want to opt out:

NANOCLAW_NO_DIAGNOSTICS=1 bash nanoclaw.sh

Prebuilt images and optional community services may require an account and transmit metadata. Local compilation is the default path. Calls to external LLM providers transmit the content necessary to respond; review their data handling policy.

8. Real Isolation: Controls You Must Review

Docker and Filesystem

• Run containers without --privileged, without access to the Docker socket, and with a restricted user if the runtime allows it.
• Avoid mounting the entire home directory, ~/.ssh, third-party client repositories, password managers, and cloud directories.
• Give read-only access to reference materials; mount write access only where strictly necessary.
• Separate folders for each agent group and its memory.
• Review container.json per group, volumes, mounts, and effective permissions.
• If a container writes to a bind mount, that write affects the host: container ≠ read-only.

Network and Exfiltration

• Even if there is no raw key inside the container, the agent could use an allowed API to do something improper, or exfiltrate information through a network egress if it knows about it.

• Review the gateway's egress/hostname policies and apply firewall/egress per container where appropriate.

• Block cloud metadata services (169.254.169.254) and unnecessary internal hosts if they are reachable by untrusted agents.

• A container can be compromised and so can the Docker daemon/host; consider kernel, container runtime, and dependency updates.### Identity control

• In v2, owner and admin user roles are defined (global or scoped), plus group membership and unknown sender policy.

• Unknown sender policy: strict, request_approval or public, depending on the migration documentation. Prioritize strict or manual approval for a private bot.

• Do not assume that a channel is private just because of its name, a mention or a trigger word.

Prompt injection and permissions

Even with Docker, an adversarial message can instruct the agent to delete files from a mounted volume, leak accessible data or execute connected tools. The effective boundary is the combination of volume scope, network, secrets, service permissions and roles, not just the prompt.

9. Alternative providers/models

The v2 stack uses the Claude Agent SDK as the source provider. The README lists integrations via skills:

• /add-codex: OpenAI Codex runtime, with whatever authentication form the integration supports.
• /add-opencode: other providers/models through OpenCode.
• /add-ollama-provider: local open-weight models with Ollama.

Skill commands are sent inside Claude Code from the checkout. Their compatibility with a specific model, tool handling and performance must be verified case by case. Do not assume that a compatible API guarantees all tool calls and the same memory behavior.

Model per agent group: documented in the README; useful for reserving powerful models for critical jobs and cheap ones for summaries. To evaluate real cost, record: requests, input/output tokens, tool repetitions, tool calling errors and container hours.

10. Customization, templates and MCP

Customization is maintained in a fork through code and skills:

• High flexibility: you can write new integrations and review the code that runs.
• Higher maintenance: you must manage your fork when updating upstream.
• Risk of introducing vulnerabilities during automated "customize"; review the diff.

Templates

The v2 documentation states:

ncl groups create --template <ref>

Replace <ref> with a legitimate template and verify that the ncl CLI was installed in your environment. Templates combine instructions, skills and MCP without secrets. Review the tools the template includes before running it with real credentials. Reference: https://github.com/nanocoai/nanoclaw/blob/main/docs/templates.md

MCP / self-modification

The runner includes an MCP tool registry, and the v2 notes mention self-modification flows for installing packages or adding MCP servers with administrative approval and image rebuild. Review the current version of that flow: running a third-party MCP is adding code to the agent's trust context.

11. VPS operation: monitoring and troubleshooting

The installer manages the services; their names depend on the system and version. Use these Docker tools to inspect the deployment:

cd nanoclaw-v2
git rev-parse --short HEAD
node --version
pnpm --version
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
docker stats --no-stream
docker system df

For an identified and trusted container:

docker logs --tail=100 NOMBRE_O_ID_DEL_CONTENEDOR
# Examina mounts y límites antes de cambiar permisos:
docker inspect NOMBRE_O_ID_DEL_CONTENEDOR

If setup or behavior fails, the README recommends opening claude from the checkout and using the /debug skill; treat change proposals as a PR, not as orders to approve automatically.

Quick incident table

Record and retain in encrypted form:

• exact commit SHA of the fork and customization files;
• data/ (includes central and per-session DB), gateway state if applicable;
• groups/ and memory/instructions;
• credentials in a separate secrets manager (backing up .env is not enough);
• channel state/authentication, depending on the installed adapter;
• deployment scripts/env and manifests actually used.

Perform consistent backups: stop processes appropriately or use a consistent SQLite copy; do not indiscriminately rsync-copy active databases and assume consistency. Test restoring in a separate environment without connecting it to real channels to avoid duplicate sends.

Upgrade (operational proposal)

1. Backup + snapshot of VPS/volumes.
2. Note the current SHA and review releases/changelog.
3. Bring upstream changes into your fork, resolve conflicts in skills/modifications.
4. Review changes in schema and credentials gateway.
5. Rebuild/test the image and channels in a staging installation.
6. Migrate to production with a rollback plan.

Review upstream changes before integrating them into a customized fork.

Official uninstall

The README describes:

bash nanoclaw.sh --uninstall --dry-run   # vista previa
bash nanoclaw.sh --uninstall             # solicita confirmaciones

The uninstall may delete the service, containers, images, data, logs and agent files linked to that checkout. Keep a backup beforehand, read the preview and confirm you are in the correct folder. Shared credentials/gateway may survive and require separate review.

12. Migration v1 → v2: key changes

• v1: a Node host with a single SQLite DB for messages, groups and tasks; v2: host + central DB + two per-session DBs + Bun containers.
• v1: relatively flat chat→group association; v2: users, roles, messaging groups, agent groups and multiple session schemas.
• v1: more direct env/secrets; v2: credentials gateway.
• v1: embedded channels; v2: skills that copy/adapt modules into your fork.
• v1: chat history; the migrator does not automatically preserve the entire message history (the docs state this explicitly).

The official path is to clone a clean v2 installation alongside v1 and run from v2:

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash migrate-v2.sh

The migrator detects the nearby v1 or uses NANOCLAW_V1_PATH=/ruta/a/v1; it copies components and then Claude Code handles decisions (owner, memory, customizations). It does not automatically perform the service switchover unless authorized. Never migrate directly on top of the only copy of your data.

Source: https://github.com/nanocoai/nanoclaw/blob/main/docs/v1-to-v2-changes.md

13. Isolation validation

• Create two agent groups with different files and memory; verify their separation.
• Test owner, unknown senders and permissions from an unauthorized account.
• Inspect mounts and secret rules: no Docker socket or full home, with selective mode where applicable.
• Rehearse untrusted inputs, resource limits and backup restoration in a test environment.

14. Official sources

1. Main README, v2 installation
2. Channel/agent isolation model
3. Architecture
4. Changes from v1 to v2
5. Templates
6. Optional community portal
7. Security