11 KiB

Raw Blame History

OpenHands Integration Status Report

Date: 2025-11-30 Phase: OpenHands CLI Integration Testing Status: Technical Blocker Identified

Executive Summary

We attempted to integrate OpenHands with n8n workflows using both API and CLI approaches. While both methods show partial functionality, there are technical blockers preventing full automation:

API Approach: Conversations can be created, but runtime containers fail to start due to network namespace isolation
CLI Approach: Works interactively but requires TTY for auto-confirmation, which is problematic in non-TTY environments (like n8n SSH nodes)

What We Tested

1. OpenHands CLI Direct Execution

Command: /home/bam/.local/bin/openhands -t "Create a file"

Result:

✅ CLI starts successfully
✅ Agent initializes with MiniMax-M2 model
✅ Task is processed and action created
❌ BLOCKER: Waits for interactive confirmation ("Choose an option:")
❌ File not created in non-TTY environment

Output Log:

Predicted Security Risk: LOW
Agent Action created, waiting for confirmation
Choose an option:
  Yes, proceed
  Reject
  Always proceed (don't ask again)

No input received; pausing agent.

2. OpenHands API Approach

Test: Create conversation via HTTP API

Command:

curl -X POST http://localhost:3000/api/conversations \
  -H "Content-Type: application/json" \
  -d '{"initial_user_msg": "Create a file"}'

Result:

✅ Conversation created successfully (ID: a23d491e55ae4e0995b563a54705d59c)
❌ BLOCKER: Runtime stuck at "STATUS$STARTING_RUNTIME"
❌ Network namespace isolation prevents runtime container from connecting

Status Response:

{
  "status": "STARTING",
  "runtime_status": "STATUS$STARTING_RUNTIME",
  "conversation_id": "a23d491e55ae4e0995b563a54705d59c"
}

3. CLI Automation Attempts

Attempt 1: Python Wrapper (subprocess.PIPE)

File: /home/bam/run-openhands.py

Result:

Created wrapper with stdin pipe
Still receives TTY warning: "Warning: Input is not a terminal (fd=0)"
Auto-confirmation logic attempted but unreliable

Attempt 2: Bash Script with Timeout

File: /home/bam/test-openhands-cli.sh

Result:

Uses piped input: echo -e "task\ny" | openhands -t ""
❌ Input not properly received
Task starts but never completes

Attempt 3: Python with pty Module

File: /home/bam/openhands-pty.py

Result:

Created pseudo-TTY for proper terminal emulation
Uses select() for async I/O
⏳ Still running during test (potential solution)

n8n Workflows Created

We created three n8n workflow configurations:

1. Simple CLI Workflow

File: /home/bam/claude/mvp-factory/openhands-cli-simple.json

Single SSH node
Direct CLI execution
Expected to fail due to TTY issues

2. tmux-based Workflow

File: /home/bam/claude/mvp-factory/openhands-cli-tmux-workflow.json

Uses tmux for session management
Attempts to run CLI in persistent session
May work but untested

3. Complete Workflow with Webhook

File: /home/bam/claude/mvp-factory/openhands-n8n-workflow.json

Webhook trigger for Gitea integration
SSH execution node
Verification node
Response node
BEST CANDIDATE for testing

Root Cause Analysis

Network Namespace Isolation Issue

Problem: OpenHands server runs on host network, but runtime containers are in bridge network. The --add-host host.docker.internal:host-gateway flag resolves DNS but not port connectivity.

Evidence:

API responds on http://localhost:3000
Conversation creation succeeds
Runtime startup fails silently
Status remains "STATUS$STARTING_RUNTIME"

TTY/Interactive Input Issue

Problem: OpenHands CLI requires interactive confirmation for security, but n8n SSH nodes don't provide TTY.

Evidence:

"Warning: Input is not a terminal (fd=0)"
"Choose an option:" prompt appears
Piped input not properly handled
Auto-confirmation doesn't trigger

Potential Solutions

Solution 1: Improve Python Wrapper

Approach: Enhance /home/bam/run-openhands.py or /home/bam/openhands-pty.py

Implementation:

Use pexpect library (if available) for robust interaction
Implement proper response timing
Add retry logic
Test thoroughly

Pros:

Works within existing setup
No infrastructure changes
Reusable for other automation

Cons:

Requires Python library installation
May still have timing issues

Solution 2: Use tmux in n8n

Approach: Use tmux for persistent sessions in SSH node

Implementation:

tmux new-session -d -s task
tmux send-keys -t task 'openhands -t "task"' C-m
sleep 30
tmux capture-pane -t task -p

Pros:

Provides proper TTY
Industry-standard approach
Works with existing SSH

Cons:

Adds session management complexity
Requires tmux on target system
May timeout on long tasks

Solution 3: Use OpenHands Built-in Automation

Approach: Check if OpenHands has non-interactive or batch mode

Commands to check:

openhands --help
openhands -h
cat ~/.openhands/settings.json

Pros:

Official solution
Most reliable
Supported by upstream

Cons:

May not exist in current version (1.3.0)

Solution 4: API with Fixed Runtime

Approach: Fix network namespace issue for API approach

Implementation:

Use host networking for runtime (dangerous)
Custom Docker network configuration
Different runtime architecture

Pros:

Clean API interface
Better error handling
Proper status monitoring

Cons:

Requires significant infrastructure changes
Security implications
May break other functionality

Current Workflow Architecture

Gitea Push → n8n Webhook → SSH Node → OpenHands CLI → File Creation
                  ↓
            Verification Node
                  ↓
            Response to Gitea (optional)

Webhooks:

Gitea → https://n8n.oky.sh/webhook/openhands-task
n8n will execute OpenHands task
Verify file creation
Return status to Gitea (future enhancement)

Immediate Next Steps

Option 1: Continue with CLI Approach (Recommended)

Test the openhands-pty.py wrapper more thoroughly
If it works, update n8n workflow to use it
Test with real Gitea webhook
Add error handling and timeouts

Option 2: Debug API Runtime Issue

Check Docker logs for runtime startup errors
Test network connectivity between containers
Try different Docker networking modes
If fixed, use API approach (cleaner)

Option 3: Hybrid Approach

Use API to create conversation
Use CLI to execute task
Monitor status via API
Best of both worlds?

Files Created/Modified

/home/bam/
├── run-openhands.py              # Python wrapper (original)
├── openhands-pty.py              # Python wrapper with pty
├── test-openhands-cli.sh         # Bash test script
├── start-openhands-fixed.sh      # Docker startup script
└── claude/mvp-factory/
    ├── openhands-cli-simple.json           # Simple workflow
    ├── openhands-cli-tmux-workflow.json    # tmux-based workflow
    ├── openhands-n8n-workflow.json         # Complete workflow
    └── OPENHANDS_INTEGRATION_STATUS.md     # This file

Testing Required

Pre-Production Testing

Wrapper Script Testing
- Test /home/bam/openhands-pty.py with simple task
- Verify file creation works
- Test timeout handling
- Test error handling
n8n Workflow Testing
- Import /home/bam/claude/mvp-factory/openhands-n8n-workflow.json
- Configure SSH credentials
- Test webhook manually
- Check execution logs
End-to-End Testing
- Configure Gitea webhook
- Push to test repository
- Verify workflow triggers
- Check OpenHands execution
- Verify file creation
Integration Testing
- Test with real project (not just file creation)
- Test npm install & build
- Test error scenarios
- Test timeout handling

Risks and Considerations

Security Risks

OpenHands has sudo access in container
SSH credentials stored in n8n
Webhook endpoints exposed publicly
Runtime isolation issues

Reliability Risks

TTY issues may prevent automation
Network namespace problems
Timeout handling inadequate
No retry logic currently

Operational Risks

Long-running tasks in SSH node
Session management complexity
Log storage and rotation
Resource consumption

Success Criteria

To consider this integration complete:

✅ OpenHands can be triggered via n8n
✅ Task executes successfully (not just starts)
✅ File/folder creation verified
✅ Gitea webhook triggers workflow
✅ End-to-end flow works (Push → Build → Verify)
✅ Error handling and timeouts implemented
✅ Documentation updated

Recommendations

Immediate (Today)

Test openhands-pty.py thoroughly
- If it works: Use in n8n workflow
- If not: Debug and improve
Use /home/bam/claude/mvp-factory/openhands-n8n-workflow.json
- Most complete workflow
- Ready for testing
- Good documentation

Short-term (This Week)

Fix remaining TTY/automation issues
Add proper error handling
Test with real build tasks
Configure Gitea webhook properly

Long-term

Investigate API runtime fix
Add retry logic and timeouts
Implement proper status reporting
Add logging and monitoring

Conclusion

The OpenHands integration is partially functional but has technical blockers preventing full automation. Both API and CLI approaches work partially:

CLI: Starts but doesn't complete due to TTY issues
API: Creates conversations but runtime fails to start

Next action: Test the openhands-pty.py wrapper and if successful, integrate into n8n workflow for full automation testing.

Appendix: Command Reference

Test OpenHands CLI Directly

/home/bam/.local/bin/openhands -t "Create a test file"
# Press 'y' when prompted, then 'exit'

Test Python Wrapper

python3 /home/bam/run-openhands.py "Create a file"
# Or
python3 /home/bam/openhands-pty.py "Create a file"

Test API Directly

curl -X POST http://localhost:3000/api/conversations \
  -H "Content-Type: application/json" \
  -d '{"initial_user_msg": "Create a file"}'

Check n8n Workflows

curl -u admin:password https://n8n.oky.sh/api/v1/workflows

Monitor OpenHands Server

docker logs -f openhands-app
# Or if running via systemd
sudo journalctl -u openhands.service -f

End of Report

11 KiB Raw Blame History

OpenHands Integration Status Report

Executive Summary

What We Tested

1. OpenHands CLI Direct Execution

2. OpenHands API Approach

3. CLI Automation Attempts

Attempt 1: Python Wrapper (subprocess.PIPE)

Attempt 2: Bash Script with Timeout

Attempt 3: Python with pty Module

n8n Workflows Created

1. Simple CLI Workflow

2. tmux-based Workflow

3. Complete Workflow with Webhook

Root Cause Analysis

Network Namespace Isolation Issue

TTY/Interactive Input Issue

Potential Solutions

Solution 1: Improve Python Wrapper

Solution 2: Use tmux in n8n

Solution 3: Use OpenHands Built-in Automation

Solution 4: API with Fixed Runtime

Current Workflow Architecture

Immediate Next Steps

Option 1: Continue with CLI Approach (Recommended)

Option 2: Debug API Runtime Issue

Option 3: Hybrid Approach

Files Created/Modified

Testing Required

Pre-Production Testing

Risks and Considerations

Security Risks

Reliability Risks

Operational Risks

Success Criteria

Recommendations

Immediate (Today)

Short-term (This Week)

Long-term

Conclusion

Appendix: Command Reference

Test OpenHands CLI Directly

Test Python Wrapper

Test API Directly

Check n8n Workflows

Monitor OpenHands Server

11 KiB

Raw Blame History