Getting Started

2 min read

Get nclaw running in minutes.

Prerequisites

Docker

The recommended way to run nclaw. The container serves as a security sandbox, and the image ships with all the tools the assistant might need.

docker run -d --name nclaw \
  -e NCLAW_TELEGRAM_BOT_TOKEN=your-token \
  -e NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id \
  -e NCLAW_DATA_DIR=/app/data \
  -v ./data:/app/data \
  -v ~/.claude/.credentials.json:/root/.claude/.credentials.json:ro \
  ghcr.io/nickalie/nclaw:latest

The Docker image is based on node:24-alpine and includes Claude Code, git, gh CLI, Chromium, Go, Node.js, and Python/uv. The assistant can install any additional packages at runtime as the task requires (e.g. apk add ffmpeg, pip install pandas, npm install -g typescript).

Kubernetes (Helm)

The Helm chart is published as an OCI artifact to GHCR.

helm install nclaw oci://ghcr.io/nickalie/charts/nclaw \
  --set env.telegramBotToken=your-token \
  --set env.whitelistChatIds=your-chat-id \
  --set claudeCredentialsSecret=my-claude-secret

Create the Claude credentials secret beforehand:

kubectl create secret generic my-claude-secret \
  --from-file=credentials.json=$HOME/.claude/.credentials.json

See the configuration page for the full list of Helm values.

Running without Docker

nclaw is a regular executable and can run directly on any machine. The only runtime dependency is Claude Code CLI — it must be installed and available in PATH.

Security notice: Without Docker, Claude Code runs directly on the host with the same permissions as the nclaw process. It has full access to the file system, network, and any credentials available to the user. Run under a dedicated unprivileged user and avoid running as root. For production use, Docker or Kubernetes deployment is strongly recommended.

Installation

Homebrew (macOS/Linux)

brew install --cask nickalie/apps/nclaw

Scoop (Windows)

scoop bucket add nickalie https://github.com/nickalie/scoop-bucket
scoop install nclaw

Chocolatey (Windows)

choco install nclaw

Winget (Windows)

winget install nickalie.nclaw

AUR (Arch Linux)

yay -S nclaw-bin

DEB / RPM / APK

Download the appropriate package from the Releases page:

# Debian/Ubuntu
sudo dpkg -i nclaw_*.deb

# Fedora/RHEL
sudo rpm -i nclaw_*.rpm

# Alpine
sudo apk add --allow-untrusted nclaw_*.apk

Binary download

Pre-built binaries for Linux, macOS, and Windows (amd64/arm64) are available on the Releases page.

Go install

CGO_ENABLED=1 go install github.com/nickalie/nclaw/cmd/nclaw@latest

Requires Go 1.25+ and a C compiler (CGO is needed for SQLite).

Usage

  1. Install Claude Code CLI and authenticate:
    curl -fsSL https://claude.ai/install.sh | bash
claude login
  2. Create a .env file or export environment variables:
    export NCLAW_TELEGRAM_BOT_TOKEN=your-token
export NCLAW_TELEGRAM_WHITELIST_CHAT_IDS=your-chat-id
export NCLAW_DATA_DIR=./data
  3. Run:
    nclaw

Any tools you want the assistant to use (git, gh, python, etc.) should be installed on the host. The assistant will use whatever is available in the system PATH.

Next Steps

Configuration