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)

Build Image:
```
docker build -t clawdbox .
```

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.