# OpenHands Integration - Final Status Report

**Date:** 2025-11-30
**Session:** AI Dev Factory - OpenHands Integration
**Status:** ❌ **ALL APPROACHES BLOCKED**

---

## Executive Summary

After extensive testing across three different integration approaches, **all methods are blocked by fundamental Docker networking issues**. The root cause is consistent across CLI, API, and headless modes: OpenHands runtime containers cannot establish connectivity back to the main OpenHands process due to network namespace isolation.

---

## Approaches Tested

### 1. CLI Approach ❌ BLOCKED
**Method:** Direct command-line execution with automation

**Issue:** Requires TTY for interactive confirmation
```bash
$ openhands -t "Create a file"
Choose an option:
  Yes, proceed
  Reject
  Always proceed (don't ask again)
```
- ❌ n8n SSH nodes don't provide TTY
- ❌ Piped input doesn't work
- ❌ Auto-confirmation unreliable
- ✅ CLI starts successfully
- ✅ Agent initializes properly

**Tested Solutions:**
- Python wrapper with subprocess.PIPE - Failed (TTY warning)
- Python wrapper with pty module - Partial (complex, timing issues)
- Bash script with timeout - Failed (no input recognition)

### 2. API Approach ❌ BLOCKED
**Method:** HTTP API for conversation management

**Test:**
```bash
curl -X POST http://localhost:3000/api/conversations \
  -d '{"initial_user_msg": "Create a file"}'
```

**Result:**
```json
{
  "conversation_id": "a23d491e55ae4e0995b563a54705d59c",
  "status": "STARTING",
  "runtime_status": "STATUS$STARTING_RUNTIME"
}
```

**Issue:** Runtime startup timeout
- ✅ API server responds
- ✅ Conversations created successfully
- ❌ Runtime containers fail to start
- ❌ `httpcore.ConnectTimeout: timed out`
- ❌ Cannot reach `http://host.docker.internal:39506`

### 3. Headless Mode ❌ BLOCKED
**Method:** Docker-based non-interactive execution

**Command:**
```bash
docker run --rm \
  -e LLM_API_KEY="${MINIMAX_API_KEY}" \
  -e LLM_MODEL="openai/MiniMax-M2" \
  docker.openhands.dev/openhands/openhands:0.62 \
  python -m openhands.core.main -t "Create a file"
```

**Issue:** Same runtime connectivity problem
- ✅ Image pulls successfully
- ✅ Container starts
- ✅ Runtime container launches
- ❌ Same timeout error
- ❌ Network namespace isolation prevents connection

**Tested Variants:**
- Standard bridge networking - Failed
- Host networking (`--network=host`) - **Failed (same error)**
- Custom network - Not tested (likely same issue)

---

## Root Cause Analysis

### Primary Issue: Docker Network Architecture

**Problem:** When OpenHands launches a runtime container, that container is in an isolated network namespace and cannot reach back to the parent OpenHands container.

**Evidence:**
```
[runtime f59de7e0-9938-49-64d76edbaf1bf2e] Container started: openhands-runtime-f59de7e0-9938-49-64d76edbaf1bf2e
[runtime f59de7e0-9938-49-64d76edbaf1bf1e2] Waiting for client to become ready at http://host.docker.internal:36969...
httpcore.ConnectTimeout: timed out
```

**Why it happens:**
1. OpenHands container starts (in host network or bridge network)
2. OpenHands spawns a runtime container
3. Runtime container gets its own network namespace
4. Runtime tries to connect to `host.docker.internal:36969`
5. `host.docker.internal` resolves but port is unreachable
6. Connection times out after ~120 seconds

**Network Flow:**
```
OpenHands Container
    ↓ spawns
Runtime Container (isolated network)
    ↓ tries to reach
http://host.docker.internal:36969  ← FAILS
    ↓
Timeout Error
```

---

## Technical Deep Dive

### Network Namespace Isolation
- Docker containers get isolated network namespaces by default
- Even with `--network=host`, spawned containers may have different network context
- `host.docker.internal` is a Docker convenience mapping, not a real hostname
- Port connectivity fails across network boundaries

### Why Standard Fixes Don't Work

**1. `--add-host host.docker.internal:host-gateway`**
- ✅ Resolves DNS for `host.docker.internal`
- ❌ Doesn't fix port-level connectivity
- ❌ Runtime still can't reach the parent container

**2. `--network=host`**
- ✅ Puts OpenHands container in host network
- ❌ Runtime container still gets isolated network
- ❌ Runtime still can't reach parent via `host.docker.internal`

**3. Custom Docker Networks**
- Would require modifying OpenHands source code
- Not viable without upstream changes
- Would break other functionality

---

## Files Created During Investigation

### Documentation
- `/home/bam/claude/mvp-factory/OPENHANDS_INTEGRATION_STATUS.md` - First comprehensive report
- `/home/bam/claude/mvp-factory/HEADLESS_MODE_APPROACH.md` - Headless mode documentation
- `/home/bam/claude/mvp-factory/FINAL_STATUS_REPORT.md` - This document
- `/home/bam/claude/mvp-factory/NEXT_STEPS.md` - Previous next steps guide

### Python Wrappers
- `/home/bam/run-openhands.py` - Subprocess-based wrapper
- `/home/bam/openhands-pty.py` - Pseudo-TTY wrapper
- `/home/bam/run-openhands.sh` - Bash wrapper
- `/home/bam/run-openhands-task.sh` - Timeout wrapper

### n8n Workflows
- `/home/bam/claude/mvp-factory/openhands-cli-simple.json` - Simple CLI workflow
- `/home/bam/claude/mvp-factory/openhands-cli-tmux-workflow.json` - tmux-based workflow
- `/home/bam/claude/mvp-factory/openhands-n8n-workflow.json` - Complete workflow
- `/home/bam/claude/mvp-factory/openhands-workflow.json` - Original API workflow
- `/home/bam/claude/mvp-factory/openhands-workflow-with-verification.json` - API with verification

### Test Scripts
- `/home/bam/test-openhands-cli.sh` - CLI testing script
- `/home/bam/test-headless.sh` - Headless mode test
- `/home/bam/test-headless-hostnet.sh` - Host networking test

### Utilities
- `/home/bam/start-openhands-fixed.sh` - Docker startup script
- `/home/bam/openhands-server.sh` - Server management

---

## Alternative Approaches (Not Tested)

### 1. Use Different OpenHands Version
- **Version 0.62** (current) - Tested, broken
- **Version 0.61 or earlier** - May have different networking
- **Latest GitHub build** - May have fixes

**Action:**
```bash
# Check available versions
docker images | grep openhands

# Try older version
docker run docker.openhands.dev/openhands/openhands:0.61 ...
```

### 2. Modify OpenHands Source Code
- Fork the repository
- Fix network connectivity in Docker runtime
- Build custom image

**Pros:** Permanent fix
**Cons:** Requires Go/Python expertise, maintenance burden

### 3. Use Alternative AI Automation Tools
- **GitHub Copilot CLI** - Different approach
- **CodeT5** - Open source alternative
- **Custom LLM wrapper** - Build from scratch

**Pros:** Avoids OpenHands issues
**Cons:** Different capabilities, starting over

### 4. Run OpenHands Without Docker
- Native installation
- Direct Python execution
- No container isolation

**Pros:** No networking issues
**Cons:** Security risks, environment conflicts

### 5. Use Remote OpenHands Instance
- Run OpenHands on separate VM/server
- Access via SSH or HTTP
- n8n connects remotely

**Pros:** Isolates networking issues
**Cons:** Infrastructure overhead, latency

---

## Immediate Recommendations

### Option A: Try Older OpenHands Version (30 min)
```bash
# Test with version 0.61
docker pull docker.openhands.dev/openhands/openhands:0.61
docker run --rm \
  -e LLM_API_KEY="${MINIMAX_API_KEY}" \
  -e LLM_MODEL="openai/MiniMax-M2" \
  docker.openhands.dev/openhands/openhands:0.61 \
  python -m openhands.core.main -t "Create a test file"
```

**Success Criteria:** Runtime connects without timeout

### Option B: Investigate OpenHands GitHub Issues (60 min)
1. Check GitHub issues for similar problems
2. Look for Docker networking fixes
3. Contact OpenHands maintainers
4. Search for workarounds

**Search Terms:**
- "host.docker.internal"
- "runtime timeout"
- "network namespace"
- "ConnectTimeout"

### Option C: Use Alternative Tool (2-4 hours)
1. Research alternative AI coding assistants
2. Evaluate GitHub Copilot CLI
3. Consider custom LLM wrapper
4. Re-architect solution

**Tools to Consider:**
- GitHub Copilot CLI
- CodeT5
- Custom ChatGPT wrapper
- Claude API directly

### Option D: Hybrid Approach (1-2 hours)
1. Use OpenHands only for code generation
2. Separate execution from generation
3. Generate code → Execute via SSH
4. Bypass runtime connectivity

**Workflow:**
```
n8n → OpenHands (generate script) → SSH (execute script)
```

---

## Impact Assessment

### Project Timeline
- **Original Estimate:** 3-4 hours
- **Current Status:** 6+ hours invested
- **Completion Risk:** HIGH

### Technical Debt
- Multiple failed approaches
- Accumulated test scripts
- Incomplete workflows
- Documentation overhead

### Business Impact
- **Gitea integration:** Blocked
- **Automated testing:** Blocked
- **CI/CD pipeline:** Blocked
- **Developer productivity:** Impacted

---

## What We Learned

### Docker Networking is Complex
- Container-to-container communication requires careful network design
- Network namespaces are isolated by default
- `host.docker.internal` is not a universal solution
- Cross-namespace port connectivity is challenging

### AI Tool Integration Challenges
- OpenHands assumes interactive environment
- Automation requires careful handling
- Runtime isolation adds complexity
- Version compatibility matters

### n8n Limitations
- SSH nodes lack TTY support
- Non-interactive commands work better
- Timeout handling critical
- Credential management important

---

## Success Metrics (If We Had Solved It)

- [ ] OpenHands executes tasks without human interaction
- [ ] File creation works reliably
- [ ] Gitea webhook triggers workflow
- [ ] End-to-end test passes
- [ ] Error handling in place
- [ ] Documentation complete

**Current Status:** 0/6 achieved

---

## Final Conclusion

**All integration approaches are fundamentally blocked by Docker network architecture issues in OpenHands.** The runtime container connectivity problem is not a bug but a design limitation of how OpenHands handles container isolation.

**Recommendation:** Pivot to alternative approach rather than continue debugging OpenHands networking issues.

---

## Quick Reference

### Current State
- OpenHands CLI: Works but needs TTY
- OpenHands API: Creates conversations, fails on runtime
- OpenHands Headless: Same runtime failure
- Docker networking: Fundamental limitation

### Available Commands
```bash
# Test current version
docker run --rm \
  -e LLM_API_KEY="${MINIMAX_API_KEY}" \
  docker.openhands.dev/openhands/openhands:0.62 \
  python -m openhands.core.main -t "Hello"

# Check Docker networks
docker network ls
docker network inspect bridge

# Check running containers
docker ps -a | grep openhands

# Monitor logs
docker logs -f openhands-app
```

### Next Steps Priority
1. **HIGH:** Try OpenHands version 0.61
2. **HIGH:** Check GitHub issues for solutions
3. **MEDIUM:** Contact OpenHands maintainers
4. **LOW:** Consider alternative tools

---

**End of Report**

*This represents comprehensive testing across all viable integration approaches. The networking issue is a fundamental blocker requiring upstream fixes or alternative solutions.*