DEPLOYMENT.md

Deployment Guide: Clawdbot to HuggingFace Spaces

Quick Start (5 minutes)

Step 1: Create HuggingFace Account

1. Go to https://huggingface.co
2. Sign up (free tier available)
3. Generate API token:
   • Settings → Access Tokens
   • Create "Read" token
   • Copy token (you'll need it)

Step 2: Create New Space

1. Click "+ New" → "Space"
2. Configure:
   • Space name: clawdbot-dev (or your choice)
   • License: MIT
   • SDK: Docker
   • Hardware: CPU Basic (free) or upgrade for faster inference
3. Click "Create Space"

Step 3: Upload Files

Upload these files to your Space:

• app.py
• recursive_context.py
• Dockerfile
• requirements.txt
• README.md
• .gitignore

Via Git (Recommended):

# Clone your new Space
git clone https://huggingface.co/spaces/your-username/clawdbot-dev
cd clawdbot-dev

# Copy all files from this directory
cp /path/to/clawdbot-dev/* .

# Commit and push
git add .
git commit -m "Initial deployment of Clawdbot"
git push

Via Web Interface:

• Click "Files" tab
• Click "Add file" → "Upload files"
• Drag and drop all files
• Commit changes

Step 4: Configure Secrets

1. Go to Space Settings → Repository Secrets

2. Add secrets:

   Name: HF_TOKEN
   Value: [your HuggingFace API token from Step 1]
   

   Optional - if you have E-T Systems on GitHub:

   Name: REPO_URL
   Value: https://github.com/your-username/e-t-systems
   

Step 5: Wait for Build

• Space will automatically build (takes ~5-10 minutes)
• Watch "Logs" tab for progress
• Build complete when you see: "Running on local URL: http://0.0.0.0:7860"

Step 6: Access Your Assistant

• Click "App" tab
• Your Clawdbot is live!
• Access from iPhone browser: https://your-username-clawdbot-dev.hf.space

Troubleshooting

Build Fails

Check logs for:

• Missing dependencies → Verify requirements.txt
• Docker errors → Check Dockerfile syntax
• Out of memory → Upgrade to paid tier or reduce context size

Common fixes:

# View build logs
# Settings → Logs

# Restart build
# Settings → Factory Reboot

No Repository Access

If you see "No files indexed":

1. Option A: Mount via Secret

   • Add REPO_URL secret with your GitHub repo
   • Restart Space
   • Repository will be cloned on startup

2. Option B: Direct Upload

   # In your Space's git clone
   mkdir -p workspace/e-t-systems
   cp -r /path/to/your/e-t-systems/* workspace/e-t-systems/
   git add workspace/
   git commit -m "Add E-T Systems codebase"
   git push
   

3. Option C: Demo Mode

   • Space creates minimal demo structure
   • Upload files via chat interface
   • Good for testing

Slow Responses

Qwen2.5-Coder-32B on free tier has cold starts.

Solutions:

• Upgrade to GPU (paid tier) for faster inference
• Switch to smaller model (edit app.py):

  client = InferenceClient(
      model="bigcode/starcoder2-15b",  # Smaller, faster
      token=os.getenv("HF_TOKEN")
  )
  

• Use HF Pro subscription for priority access

Rate Limits

Free tier has inference limits.

Solutions:

• Upgrade to HF Pro ($9/month)
• Add delays between requests
• Use local model (requires GPU tier)

Advanced Configuration

Custom Model

Edit app.py line 20:

client = InferenceClient(
    model="YOUR_MODEL_HERE",  # e.g., "codellama/CodeLlama-34b-Instruct-hf"
    token=os.getenv("HF_TOKEN")
)

Adjust Recursion Depth

Edit app.py line 121:

max_iterations = 10  # Increase for more complex queries

Add New Tools

In recursive_context.py, add method:

def your_new_tool(self, arg1, arg2):
    """Your tool description."""
    # Implementation
    return result

Then in app.py, add to TOOLS list:

{
    "type": "function",
    "function": {
        "name": "your_new_tool",
        "description": "What it does",
        "parameters": {
            # Parameter schema
        }
    }
}

And add to execute_tool():

elif tool_name == "your_new_tool":
    return ctx.your_new_tool(arguments['arg1'], arguments['arg2'])

Cost Optimization

Free Tier Strategy

• Use CPU Basic (free)
• HF Inference free tier (rate limited)
• Only index essential files
• Total: $0/month

Minimal Paid Tier

• CPU Basic (free)
• HF Pro subscription ($9/month)
• Unlimited inference
• Total: $9/month

Performance Tier

• GPU T4 Small ($0.60/hour, pause when not using)
• HF Pro ($9/month)
• Fast inference, local models
• Total: ~$15-30/month depending on usage

iPhone Access

Bookmark for Easy Access

1. Open Space URL in Safari
2. Tap Share → Add to Home Screen
3. Now appears as app icon

Shortcuts Integration

Create iOS Shortcut:

1. Get text from input
2. Get contents of URL:
   https://your-username-clawdbot-dev.hf.space/api/chat
   Method: POST
   Body: {"message": [text from step 1]}
3. Show result

Monitoring

Check Health

https://your-username-clawdbot-dev.hf.space/health

View Logs

• Settings → Logs (real-time)
• Download for analysis

Stats

• Check "Context Info" panel in UI
• Shows files indexed, model status

Updates

Update Code

cd clawdbot-dev
# Make changes
git add .
git commit -m "Update: [what changed]"
git push
# Space rebuilds automatically

Update Dependencies

Edit requirements.txt, commit, push.

Update Repository

If using REPO_URL secret:

• Space pulls latest on restart
• Or: Settings → Factory Reboot

Security

Secrets Management

• Never commit API tokens
• Use Space secrets only
• Rotate tokens periodically

Access Control

• Spaces are public by default
• For private: Settings → Change visibility to "Private"
• Requires HF Pro subscription

Support Resources

• HuggingFace Docs: https://huggingface.co/docs/hub/spaces
• Gradio Docs: https://www.gradio.app/docs
• Issues: Post in Space "Community" tab

Next Steps

1. ✅ Deploy Space
2. ✅ Test with simple queries
3. ✅ Upload your E-T Systems code
4. ✅ Try coding requests
5. 🎯 Integrate with E-T Systems workflow
6. 🎯 Add custom tools for your needs
7. 🎯 Connect to Observatory API
8. 🎯 Enable autonomous coding

---

Need help? Check Space logs or create discussion in Community tab.

Happy coding! 🦞