This guide provides an Ansible playbook to deploy NanoClaw prerequisites on Debian 10+, Ubuntu 20.04+, and RHEL 9+ compatible hosts. NanoClaw is a lightweight TypeScript AI agent framework that uses container isolation for agent sessions.
Important: NanoClaw does not publish an official Docker image and uses zero configuration files. The application runs as a Node.js process on the host system and uses Docker to spawn isolated containers for each agent session. Setup and configuration is handled interactively via Claude Code’s /setup skill—not through config files or environment variables.
This playbook provisions the host system (Node.js 20+, Docker) and clones the repository. Interactive setup (Claude API key, messaging channels) is completed manually via Claude Code after deployment.
Official Resources:
---
- name: Deploy NanoClaw prerequisites with Docker support
hosts: nanoclaw
become: true
vars:
app_root: /opt/nanoclaw
nanoclaw_repo: "https://github.com/qwibitai/nanoclaw.git"
nodejs_version: "20.x"
app_user: nanoclaw
tasks:
- name: Install Docker on Debian/Ubuntu
apt:
name:
- docker.io
- docker-compose-plugin
- curl
- git
state: present
update_cache: true
when: ansible_os_family == "Debian"
- name: Install Docker on RHEL family
dnf:
name:
- docker
- docker-compose-plugin
- curl
- git
state: present
when: ansible_os_family == "RedHat"
- name: Enable and start Docker
service:
name: docker
state: started
enabled: true
- name: Install Node.js Repository (Debian/Ubuntu)
apt:
name:
- curl
- gnupg
state: present
when: ansible_os_family == "Debian"
- name: Add NodeSource repository
shell: |
curl -fsSL https://deb.nodesource.com/setup_{{ nodejs_version }} | bash -
when: ansible_os_family == "Debian"
- name: Install Node.js on Debian/Ubuntu
apt:
name:
- nodejs
state: present
when: ansible_os_family == "Debian"
- name: Install Node.js on RHEL family
dnf:
name:
- nodejs
- npm
state: present
when: ansible_os_family == "RedHat"
- name: Verify Node.js installation
command: node --version
register: node_version
changed_when: false
- name: Create application user
user:
name: "{{ app_user }}"
shell: /bin/bash
create_home: true
groups: docker
append: true
- name: Create application directory
file:
path: "{{ app_root }}"
state: directory
mode: "0755"
owner: "{{ app_user }}"
group: "{{ app_user }}"
- name: Clone NanoClaw repository
git:
repo: "{{ nanoclaw_repo }}"
dest: "{{ app_root }}"
version: "main"
force: true
become_user: "{{ app_user }}"
- name: Set ownership
file:
path: "{{ app_root }}"
owner: "{{ app_user }}"
group: "{{ app_user }}"
recurse: true
- name: Test Docker container spawning
command: docker run --rm ubuntu:24.04 echo ok
become_user: "{{ app_user }}"
register: docker_test
changed_when: false
failed_when: docker_test.rc != 0
- name: Display deployment status
debug:
msg: |
NanoClaw prerequisites deployed!
Application directory: {{ app_root }}
Application user: {{ app_user }}
NEXT STEPS (manual - interactive setup required):
1. SSH to the server: ssh {{ app_user }}@{{ inventory_hostname }}
2. cd {{ app_root }}
3. Run: claude
4. Inside Claude Code, run: /setup
5. Follow interactive prompts to configure:
- Claude API key
- Messaging channels (WhatsApp, Telegram, etc.)
- Container runtime (Docker auto-detected on Linux)
Important: NanoClaw uses ZERO configuration files.
All setup is handled interactively via Claude Code skills.
Repository: https://github.com/qwibitai/nanoclaw
Documentation: https://nanoclaw.dev
Save the playbook as deploy-nanoclaw-docker.yml.
Create an inventory file (inventory.ini):
[nanoclaw]
server1.example.com
server2.example.com
[nanoclaw:vars]
ansible_user=deploy
ansible_ssh_private_key_file=~/.ssh/id_ed25519
ansible-playbook -i inventory.ini deploy-nanoclaw-docker.yml
After the playbook completes:
# SSH to the server as the app user
ssh nanoclaw@server1.example.com
# Navigate to the application directory
cd /opt/nanoclaw
# Start Claude Code and run setup
claude
# Then inside Claude Code, run: /setup
The /setup skill will guide you through:
| Aspect | Details |
|---|---|
| No Official Docker Image | NanoClaw runs on the host; Docker is used for agent isolation only |
| Zero Config Files | No config.json, .env, or YAML config—setup via Claude Code /setup skill |
| Node.js Required | Version 20+ installed on host |
| Docker Required | For spawning isolated agent containers |
| Claude Code Required | Interactive setup cannot be automated via Ansible |
| API Keys | Must be entered interactively during /setup (not via Ansible Vault) |
| Container Isolation | Each agent session runs in isolated Docker container |
Host System (Node.js + NanoClaw)
│
├── spawns ──→ [Docker Container: Agent Session 1]
├── spawns ──→ [Docker Container: Agent Session 2]
└── spawns ──→ [Docker Container: Agent Session 3]
Each agent session gets:
NanoClaw intentionally uses zero configuration files. This design decision:
Attempting to pre-configure via Ansible would contradict the project’s core architecture.
# SSH to server
ssh nanoclaw@server
# Check Node.js version
node --version
# Check Docker status
docker info
# Navigate to app directory
cd /opt/nanoclaw
# Run setup via Claude Code
claude
# Then run: /setup
# List agent containers (when agents are running)
docker ps
# Agent containers are spawned on-demand and cleaned up after use
Backup the following after setup:
---
- name: Backup NanoClaw data
hosts: nanoclaw
become: true
vars:
app_root: /opt/nanoclaw
app_user: nanoclaw
tasks:
- name: Create backup directory
file:
path: "{{ app_root }}/backups"
state: directory
owner: "{{ app_user }}"
- name: Backup SQLite database and group data
archive:
path:
- "{{ app_root }}/data"
- "{{ app_root }}/groups"
dest: "{{ app_root }}/backups/nanoclaw-{{ ansible_date_time.date }}.tar.gz"
owner: "{{ app_user }}"
What to backup:
data/ directory)groups/ with CLAUDE.md files)What NOT to backup:
npm install)---
- name: Update NanoClaw
hosts: nanoclaw
become: true
vars:
app_root: /opt/nanoclaw
app_user: nanoclaw
tasks:
- name: Stop NanoClaw (if running as service)
systemd:
name: nanoclaw
state: stopped
failed_when: false
- name: Pull latest code
git:
repo: "{{ nanoclaw_repo }}"
dest: "{{ app_root }}"
force: true
become_user: "{{ app_user }}"
- name: Install updated dependencies
npm:
path: "{{ app_root }}"
state: present
become_user: "{{ app_user }}"
- name: Restart NanoClaw (if running as service)
systemd:
name: nanoclaw
state: started
failed_when: false
- name: Display upgrade notes
debug:
msg: |
NanoClaw updated!
Note: If you have a running Claude Code session, restart it
to pick up code changes. Configuration is preserved in:
- SQLite database (data/)
- CLAUDE.md files (groups/)
# SSH to server
ssh nanoclaw@server
# Check Node.js version
node --version
# Check npm version
npm --version
# Check Docker daemon
docker info
# Test container spawning
docker run --rm ubuntu:24.04 echo ok
Node.js version too old:
# Install Node.js 20+
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
Docker permission errors:
# Verify user is in docker group
groups nanoclaw
# Add user to docker group if needed
sudo usermod -aG docker nanoclaw
# Log out and back in
Claude Code not found:
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code
# Or run via npx
npx @anthropic-ai/claude-code
Setup skill not working:
# Ensure you're in the nanoclaw directory
cd /opt/nanoclaw
# Start fresh Claude Code session
claude
# Run setup skill
/setup
For detailed security guidance, see NanoClaw Security.
Any questions?
Feel free to contact us. Find all contact information on our contact page.