Docker container for claudeclaw — a daemon that extends Claude Code into a personal assistant with Telegram, Discord, and Slack bridges, scheduled jobs, voice transcription, and a web dashboard.
Zero host pollution. claudeclaw depends on Bun, Node.js, and the Claude Code CLI. Running it natively means installing and maintaining all of that on your machine. The container bundles everything — your host stays clean.
Controlled access. By default the daemon can only see what you explicitly give it. Want it to access your notes? Mount that folder. Everything else on your machine is invisible to it. Running natively, claudeclaw inherits access to your entire filesystem.
Easy to run on a server. The same image runs on a VPS, home server, or cloud instance without any changes. Your personal assistant stays online even when your laptop is closed.
Instant reset. Something went wrong or you want a clean slate? docker compose down -v removes everything. No leftover config files scattered across your home directory.
Reproducible. The container always starts from a known state. No "works on my machine" issues caused by a different Bun version, a conflicting global npm package, or a PATH quirk.
claudeclaw wraps the claude CLI directly and uses your existing Claude Code credentials — it does not require an ANTHROPIC_API_KEY. Before starting the container you need to authenticate Claude Code into the persistent volume once.
Step 1 — create the volume and log in:
docker compose run --rm claudeclaw claude login
This opens an OAuth browser flow. Complete it and your credentials are saved to the volume at /root/.claude/.credentials.json. You only need to do this once — credentials persist across container restarts.
Step 2 — start the daemon:
docker compose up -d
Alternatively, if you already have Claude Code authenticated on your host machine, you can copy your credentials directly into the volume:
docker run --rm \
-v claudeclaw-data:/root/.claude \
-v ~/.claude:/host-claude:ro \
alpine cp /host-claude/.credentials.json /root/.claude/.credentials.json
git clone https://github.com/paulmeier/claudeclaw-container
cd claudeclaw-container
docker compose run --rm claudeclaw claude login # authenticate once
docker compose up -d
The web dashboard will be available at http://localhost:4632.
On first run the container will:
settings.json on the volumebase.en model (~140 MB) for voice transcriptiondev-browser Claude Code pluginThese are all cached in the volume and skipped on subsequent starts.
All configuration lives in settings.json inside the named volume at /root/.claude/claudeclaw/settings.json. The easiest ways to edit it:
Option A — edit in place after first run:
docker compose up -d
docker compose exec claudeclaw cat /root/.claude/claudeclaw/settings.json
# copy, edit locally, then:
docker compose cp settings.json claudeclaw:/root/.claude/claudeclaw/settings.json
docker compose restart
Option B — start from the example file:
cp settings.example.json settings.json
# edit settings.json with your tokens, then:
Uncomment the bind-mount line in docker-compose.yml:
volumes:
- ./settings.json:/root/.claude/claudeclaw/settings.json:ro
Do not commit
settings.json— it contains your API tokens. It is already in.gitignore. Usesettings.example.jsonas a reference; it is safe to commit.
{
"model": "sonnet", // "opus", "sonnet", or "haiku"
"web": {
"enabled": true,
"host": "0.0.0.0", // do not change — required for container networking
"port": 4632,
},
"telegram": {
"token": "", // BotFather token
"allowedUserIds": [], // numeric Telegram user IDs who can interact
"receiveEnabled": true, // set true to listen for incoming messages
},
"discord": {
"token": "", // Discord bot token
"allowedUserIds": [], // Discord snowflake user IDs (as strings)
"listenChannels": [], // channel IDs to listen in
"listenGuilds": [], // guild IDs (leave empty to listen in all guilds)
},
"slack": {
"botToken": "", // xoxb-... bot token
"appToken": "", // xapp-... app-level token (Socket Mode)
"allowedUserIds": [], // Slack member IDs
"listenChannels": [], // channel IDs to listen in
},
"heartbeat": {
"enabled": false, // periodic check-ins from the daemon
"interval": 60, // minutes between heartbeats
"prompt": "...", // prompt sent each heartbeat
"forwardToTelegram": false,
},
"security": {
"level": "moderate", // "locked", "strict", "moderate", or "unrestricted"
},
}
settings.json:
"telegram": {
"token": "123456:ABC-...",
"allowedUserIds": [987654321],
"receiveEnabled": true
}
bot scope and Send Messages + Read Message History permissionssettings.json:
"discord": {
"token": "your-bot-token",
"allowedUserIds": ["your-snowflake-id"],
"listenChannels": ["channel-id"],
"listenGuilds": ["guild-id"]
}
chat:write, channels:history, im:history scopes and install to workspacexoxb-...)connections:write scopexapp-...)settings.json:
"slack": {
"botToken": "xoxb-...",
"appToken": "xapp-...",
"allowedUserIds": ["U012AB3CD"],
"listenChannels": ["C012AB3CD"]
}
You can give claudeclaw access to any directory on your host — notes, documents, code, media — by adding bind mounts to docker-compose.yml.
Use :ro when you want claudeclaw to read files but never modify them:
services:
claudeclaw:
volumes:
- claudeclaw-data:/root/.claude # always keep this one
- /Users/you/Notes:/mnt/notes:ro
- /Users/you/Documents:/mnt/documents:ro
Inside the container those directories appear at /mnt/notes and /mnt/documents. claudeclaw can read, search, and reference them but cannot write back to your host.
Omit :ro to allow claudeclaw to create, edit, and delete files:
volumes:
- claudeclaw-data:/root/.claude
- /Users/you/Notes:/mnt/notes # full read-write
Use this when you want claudeclaw to save notes, update files, or write output back to your machine.
Use absolute paths. Relative paths and ~ don't expand in docker-compose.yml. Use the full path or an environment variable:
- ${HOME}/Notes:/mnt/notes
Choose mount paths that are easy to reference. claudeclaw will see whatever path you pick on the right side of the :. Keeping them short and under /mnt/ makes it easy to refer to them in prompts and job definitions — for example: "summarise everything in /mnt/notes from this week".
Apply least privilege. Mount read-write only for directories claudeclaw actually needs to write to. Everything else should be :ro.
Changes take effect after a restart:
docker compose down && docker compose up -d
Available at http://localhost:4632 when web.enabled is true. Shows active jobs, logs, and session status. To access it from a remote host, either expose the port via a reverse proxy or change the port mapping in docker-compose.yml.
By default the image clones the main branch. To pin to a tag or commit:
docker build --build-arg CLAUDECLAW_REF=v1.0.34 -t claudeclaw .
Everything is stored in the claudeclaw-data named volume at /root/.claude/:
| Path | Contents |
|---|---|
claudeclaw/settings.json | Your configuration |
claudeclaw/logs/ | Job and session logs |
claudeclaw/jobs/ | Scheduled job definitions |
claudeclaw/whisper/ | whisper.cpp binary + model files |
plugins/ | Installed Claude Code plugins |
npm-global/ | Globally installed npm packages + bins |
npm-cache/ | npm and npx download cache |
To back up or inspect the volume:
# Dump to a tar archive
docker run --rm -v claudeclaw-data:/data -v $(pwd):/backup alpine \
tar czf /backup/claudeclaw-backup.tar.gz -C /data .
# Restore
docker run --rm -v claudeclaw-data:/data -v $(pwd):/backup alpine \
tar xzf /backup/claudeclaw-backup.tar.gz -C /data
Some Claude Code skills (and your own prompts) call out to CLI tools via npm install -g or npx. By default those land in /usr/lib/node_modules and /root/.npm — both inside the container's writable layer and wiped on every image pull. To avoid re-installing on every update, the container redirects npm into the persistent volume so packages and the npx cache survive container recreation and image rebuilds.
On every start, entrypoint.sh exports:
| Variable | Effect |
|---|---|
NPM_CONFIG_PREFIX=/root/.claude/npm-global | Global installs go to npm-global/lib/node_modules/, executables to npm-global/bin/ |
NPM_CONFIG_CACHE=/root/.claude/npm-cache | npm and npx tarball cache |
PATH=/root/.claude/npm-global/bin:$PATH | Global binaries are on PATH for the daemon and every process it spawns (skills, jobs, docker exec) |
Because /root/.claude is the named volume, anything written under these paths sticks around across docker compose down && up, docker compose pull, and image rebuilds. The persistent layout adds these to the volume:
/root/.claude/
├── npm-global/
│ ├── bin/ # binaries on PATH
│ └── lib/node_modules/
└── npm-cache/ # npm + npx tarball cache
NPM_CONFIG_* env vars take precedence over .npmrc, so this also works if you bind-mount your own .npmrc.
From a running container, or from a Claude Code skill:
docker compose exec claudeclaw npm install -g cowsay
docker compose exec claudeclaw cowsay hello # binary persists across restarts
npx works the same way — first call downloads, subsequent calls (even after container recreation) read from the cached tarball.
If you'd rather not depend on the entrypoint running before a package is available (for example, packages needed at image-build time or referenced by other tooling), extend the base image:
FROM paulmeier/claudeclaw-container:latest
RUN npm install -g cowsay some-other-pkg
Then point docker-compose.yml at the new image:
services:
claudeclaw:
image: my/claudeclaw:latest
docker compose down -v) removes installed packages along with everything else. Use backup.sh if you want them preserved.npm install can consume significant space. du -sh /root/.claude/npm-* to audit.backup.sh snapshots the entire claudeclaw data — credentials, settings, logs, jobs, whisper models, plugins, and session history — into a timestamped archive. It can be run from the host or from inside the container.
./backup.sh
# Saved: ./backups/claudeclaw-2026-05-09-143022.tar.gz (187M)
Archives are written to ./backups/ by default. Override with CLAUDECLAW_BACKUP_DIR:
CLAUDECLAW_BACKUP_DIR=~/Backups/claudeclaw ./backup.sh
The script accesses the volume via a temporary Docker container, so it is safe to run while the daemon is running.
Mount a backup destination into the container, then run /backup.sh:
# One-off via docker compose run
docker compose run -v ~/Backups/claudeclaw:/backup claudeclaw /backup.sh
# Or exec into a running container
docker compose exec -e CLAUDECLAW_BACKUP_DIR=/backup claudeclaw /backup.sh
To make this permanent, uncomment the backup mount in docker-compose.yml:
volumes:
- claudeclaw-data:/root/.claude
- ${HOME}/Backups/claudeclaw:/backup
Then from any shell inside the container:
/backup.sh
# or with a custom path:
CLAUDECLAW_BACKUP_DIR=/backup /backup.sh
docker compose down
docker volume rm claudeclaw-data
docker run --rm \
-v claudeclaw-data:/data \
-v /path/to/backups:/backup:ro \
alpine tar xzf /backup/claudeclaw-2026-05-09-143022.tar.gz -C /data
docker compose up -d
Add to your ~/.zshrc to run a host-side backup from anywhere:
alias claudeclaw-backup='/bin/zsh -l /Users/you/Projects/claudeclaw-container/backup.sh'
Then source ~/.zshrc and call claudeclaw-backup whenever you want a snapshot.
shell.sh starts the container if it isn't running and drops you straight into the Claude CLI inside it:
./shell.sh
Create a dedicated iTerm2 profile so you can open a claudeclaw terminal from the menu or a hotkey:
+/bin/zsh -l /Users/you/Projects/claudeclaw-container/shell.sh
The -l flag loads your login shell environment so docker is on the PATH.
Add to your ~/.zshrc for one-word access from any terminal:
alias claudeclaw='/bin/zsh -l /Users/you/Projects/claudeclaw-container/shell.sh'
Then run source ~/.zshrc and type claudeclaw anywhere.
Container exits immediately
Check logs: docker compose logs. Usually a missing or malformed settings.json.
Web dashboard not loading
Ensure web.enabled is true and web.host is "0.0.0.0" in settings. The entrypoint auto-corrects 127.0.0.1 → 0.0.0.0, but other values are left as-is.
Bot not responding to messages
allowedUserIdsdocker compose logs -fWhisper download fails on first start
The container needs outbound internet access. If behind a proxy, set HTTP_PROXY / HTTPS_PROXY environment variables in docker-compose.yml.
Content type
Image
Digest
sha256:3f9774d31…
Size
607.2 MB
Last updated
22 days ago
docker pull paulmeier/claudeclaw-container