ClawdBox/README.md

# 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 (v22), 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)
- **Agent node:** self-starting OpenClaw node host helper for `ClawdBox-CLI`

## Prerequisites

Before deploying, create the kubeconfig secret to give the container kubectl/oc access:

```bash
kubectl create secret generic kube \
  --from-file=config=$HOME/.kube/breakglass-system-admin.kubeconfig \
  -n clawdbox
```

**Note:** This kubeconfig is mounted at `/home/claw/.kube/config` inside the container.

## Deployment (OpenShift / K8s)

1. **Build Image:**
   ```bash
   docker build -t clawdbox .
   ```

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

   ```yaml
   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):
```bash
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)
├── agents/
│   └── clawd/            # Durable OpenClaw agent workspace and node host
│       ├── bin/          # start/status/stop helpers and openclaw symlink
│       ├── logs/         # node-host logs and pid file
│       ├── notes/        # operator notes
│       ├── src/          # source checkouts and experiments
│       ├── tmp/          # scratch files
│       └── tools/        # persistent tool installs
├── 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)

## OpenClaw Node Host

ClawdBox runs SSH and the `ClawdBox-CLI` node host as separate containers in
the same pod. Kubernetes supervises the node container, while its identity,
runtime configuration, and exec approvals persist under
`/data/agents/clawd/node-home`.

The helper scripts are copied into `/data/agents/clawd/bin/` on each startup:

```bash
start-clawdbox-node
status-clawdbox-node
stop-clawdbox-node
```

The node host installs `openclaw@2026.7.2-beta.3` under
`/data/agents/clawd/tools/openclaw-node` if it is missing or stale. It gets the
Gateway token from `OPENCLAW_GATEWAY_TOKEN` when set, otherwise from the live
`openclaw` deployment via the mounted kubeconfig.

Useful overrides:

```bash
OPENCLAW_VERSION=2026.7.2-beta.3
OPENCLAW_GATEWAY_HOST=openclaw.apps.lab.apilab.us
OPENCLAW_GATEWAY_PORT=443
OPENCLAW_GATEWAY_TLS=true
CLAWDBOX_NODE_DISPLAY_NAME=ClawdBox-CLI
CLAWDBOX_NODE_HOME=/data/agents/clawd/node-home
```

If node startup fails, SSH remains available while Kubernetes restarts the
node container. Check `/data/agents/clawd/logs/node-host.log` for details.

## Common Tasks

### Quick Operations (Using Makefile)
```bash
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:
```bash
pip3 install --user pandas numpy scikit-learn
# Installs to /data/.local/lib/python3.*/site-packages/
```

### Install Node Packages Globally
```bash
npm install -g typescript ts-node
# Cached in /data/.cache/npm
```

### Persist Git Configuration
```bash
# 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
```bash
# 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/`:

```bash
# 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:**
```bash
# 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:**
```bash
make disk-usage
# or
ssh -p 2222 claw@clawdbox.apps.lab.apilab.us "df -h /data"
```

**Solutions:**
```bash
# 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:
```bash
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:
```bash
make redeploy
```

### Pod Stuck in CrashLoopBackOff
**Problem:** Container won't start

**Diagnosis:**
```bash
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:**
```bash
make status
# Shows: deployment, pods, services, routes
```

## Development Workflow

### Local Development
```bash
# 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:
```dockerfile
RUN apt-get update && apt-get install -y --no-install-recommends \
    # ... existing tools ...
    your-new-tool \
    && rm -rf /var/lib/apt/lists/*
```

Then:
```bash
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.