ClawdBox

A persistent sandbox environment for Clawdbot (OpenClaw).

Purpose

This container provides a stable, tool-rich environment for the AI agent to:

• Persist state across agent restarts.
• Run long-running processes.
• Perform "messy" work (compiling, scraping, data processing) without polluting the main agent container or host.
• Use tools that aren't available in the minimal agent environment.

Tools Included

• Core: curl, wget, git, jq, yq, unzip, tar, vim/nano, tree, less
• Dev: python3 (pip/venv), build-essential, nodejs (v20), npm
• Python Libraries: httpie, pyyaml, requests, black, ipython
• Network: ping, dnsutils, net-tools, openssh-server/client, sshpass
• Media: ffmpeg
• Monitoring: htop, tmux, ncdu, strace
• Kubernetes: OpenShift CLI (oc)
• Search: ripgrep (fast grep alternative)

Deployment (OpenShift / K8s)

1. Build Image:

   docker build -t clawdbox .
   

2. Run with Persistence: Ensure you mount a PVC to /data to keep files across restarts.

   apiVersion: v1
   kind: Pod
   metadata:
     name: clawdbox
   spec:
     containers:
     - name: clawdbox
       image: clawdbox:latest
       ports:
       - containerPort: 2222
       volumeMounts:
       - mountPath: /data
         name: claw-data
     volumes:
     - name: claw-data
       persistentVolumeClaim:
         claimName: clawdbox-pvc
   

Access

Connect via SSH using the claw user (passwordless sudo enabled):

ssh -p 2222 claw@clawdbox.apps.lab.apilab.us
# or
make shell

Persistent Storage Structure

The /data volume preserves data across container restarts:

/data/
├── ssh/                  # SSH host keys (auto-generated on first run)
├── scripts/              # Helper scripts (from ConfigMap, read-only)
│   ├── disk-usage.sh
│   ├── health-check.sh
│   ├── clean-workspace.sh
│   └── install-tools.sh
├── .cache/
│   ├── pip/             # Python package cache (persisted)
│   └── npm/             # Node package cache (persisted)
├── .local/              # User-installed Python packages (pip install --user)
├── .gitconfig           # Git configuration (create to persist)
├── .bash_history        # Command history (persistent)
└── [your workspace]     # Your work files

Storage: 10Gi PersistentVolumeClaim (ReadWriteOnce)

Common Tasks

Quick Operations (Using Makefile)

make help         # Show all available commands
make logs         # Stream container logs
make shell        # SSH into container
make disk-usage   # Check storage usage
make clean-cache  # Clear package caches
make redeploy     # Rebuild, push, and restart

Install Python Packages

Packages are cached in /data/.cache/pip and survive restarts:

pip3 install --user pandas numpy scikit-learn
# Installs to /data/.local/lib/python3.*/site-packages/

Install Node Packages Globally

npm install -g typescript ts-node
# Cached in /data/.cache/npm

Persist Git Configuration

# Inside the container:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
# Save to persistent storage:
cp ~/.gitconfig /data/.gitconfig
# (Will auto-link on next restart)

Check Disk Usage

# Quick overview:
df -h /data

# Use helper script for detailed report:
/data/scripts/disk-usage.sh

# Interactive explorer:
ncdu /data

# Top 10 largest directories:
du -h /data | sort -rh | head -10

Helper Scripts

Pre-loaded scripts available in /data/scripts/:

# Comprehensive health check:
/data/scripts/health-check.sh

# Disk usage report:
/data/scripts/disk-usage.sh

# Interactive workspace cleanup:
/data/scripts/clean-workspace.sh

# Install common tools:
/data/scripts/install-tools.sh

Shell Features

The shell includes several quality-of-life improvements:

• Colored prompt: claw@clawdbox:/data$ (green user, blue path)
• Persistent history: Command history saved to /data/.bash_history
• Useful aliases:
  • ll - detailed file listing (ls -lah)
  • k - kubectl shortcut
  • dc - docker shortcut
• 10,000 line history: Never lose your commands

Troubleshooting

SSH Connection Refused

Problem: Cannot connect via SSH

Diagnosis:

# Check if pod is running:
kubectl get pods -n clawdbox

# Check pod logs:
make logs
# or
kubectl logs -n clawdbox deployment/clawdbox

Common causes:

• Pod still starting (wait for startup probe to pass)
• SSH keys not mounted correctly (check secret exists)
• Route not configured (check kubectl get route -n clawdbox)

Out of Disk Space

Problem: /data volume is full

Diagnosis:

make disk-usage
# or
ssh -p 2222 claw@clawdbox.apps.lab.apilab.us "df -h /data"

Solutions:

# Clear package caches:
make clean-cache

# Find large directories:
ncdu /data

# Clear specific caches manually:
rm -rf /data/.cache/pip/*
rm -rf /data/.cache/npm/*

Slow Package Installs

Problem: pip install or npm install is slow

Diagnosis: Check if cache directories are properly configured:

ssh -p 2222 claw@clawdbox.apps.lab.apilab.us
echo $PIP_CACHE_DIR        # Should show: /data/.cache/pip
echo $npm_config_cache     # Should show: /data/.cache/npm
ls -la /data/.cache/

Solution: If environment variables are missing, rebuild the container:

make redeploy

Pod Stuck in CrashLoopBackOff

Problem: Container won't start

Diagnosis:

kubectl describe pod -n clawdbox -l app=clawdbox
kubectl logs -n clawdbox -l app=clawdbox --previous

Common causes:

• PVC not bound (check kubectl get pvc -n clawdbox)
• SSH host key generation failed (check logs for errors)
• Resource limits too low (increase in deployment.yaml)

Deployment Status

Quick health check:

make status
# Shows: deployment, pods, services, routes

Development Workflow

Local Development

# 1. Make changes to Dockerfile or manifests
vim Dockerfile

# 2. Build and test locally (optional)
docker build -t clawdbox:test .

# 3. Deploy to cluster
make redeploy

# 4. Watch for successful rollout
make logs

Adding New Tools

Edit the Dockerfile and add to the apt-get install section:

RUN apt-get update && apt-get install -y --no-install-recommends \
    # ... existing tools ...
    your-new-tool \
    && rm -rf /var/lib/apt/lists/*

Then:

make redeploy

Security Notes

• Non-root: Container runs as UID 1000 (claw user)
• SSH: Public key authentication only (no passwords)
• Sudo: Passwordless sudo available for claw user
• Capabilities: All capabilities dropped except NET_BIND_SERVICE
• Network: Ingress restricted to SSH port (2222)

Resource Limits

Requests:

• CPU: 500m
• Memory: 256Mi

Limits:

• CPU: 2000m (2 cores)
• Memory: 2Gi

Adjust in manifests/deployment.yaml if needed for heavy workloads.