7.7 KiB

Raw Blame History

n8n → OpenHands Workflow Setup Guide

Status: Ready to import and test Workflow File: /tmp/openhands-workflow.json n8n URL: https://n8n.oky.sh

📋 Step-by-Step Instructions

Step 1: Access n8n Web Interface

Open your browser and go to: https://n8n.oky.sh
Log in with your n8n credentials:
- Username: admin (or your configured username)
- Password: [your n8n password]

Step 2: Import the Workflow

In n8n, click "Workflows" in the left sidebar
Click "Add Workflow" (top right)
Click the "⋮" menu (three dots, top right)
Select "Import from File"
Upload: /tmp/openhands-workflow.json
Click "Import"

Alternative: Manual Copy-Paste If file upload doesn't work:

Copy the contents of /tmp/openhands-workflow.json
In n8n, click "⋮" menu → "Import from URL or File"
Paste the JSON directly
Click "Import"

Step 3: Review the Workflow

You should now see a workflow with these nodes:

┌─────────────────┐
│ Manual Trigger  │
└────────┬────────┘
         ↓
┌─────────────────┐
│ Create          │
│ Conversation    │  ← POST /api/conversations
└────────┬────────┘
         ↓
┌─────────────────┐
│ Wait 5s         │
└────────┬────────┘
         ↓
┌─────────────────┐
│ Get             │
│ Conversation    │  ← GET /api/conversations/{id}
│ Status          │
└────────┬────────┘
         ↓
┌─────────────────┐
│ Check If Ready  │  ← If status != STARTING
└─────┬───────┬───┘
      │       │
 Ready│       │Still Starting
      ↓       ↓
┌──────────┐ ┌──────────┐
│Get Events│ │Wait 10s  │
│          │ │More      │
└──────────┘ └────┬─────┘
                  ↓
            ┌──────────┐
            │Format    │
            │Status    │
            └────┬─────┘
                 ↓
          (Loop back to Get Status)

Step 4: Test the Workflow

Click "Save" (top right) to save the workflow
Give it a name: "OpenHands API Test"
Click "Execute Workflow" button (top right)
Click "Yes, execute" to confirm

What happens:

Creates a new OpenHands conversation
Asks OpenHands to create a file: hello.txt with content "Hello from n8n automated workflow!"
Polls the status until ready
Retrieves events to see what happened

Step 5: Monitor Execution

Watch the workflow execute in real-time
Each node will light up green as it completes
Click on any node to see its output data
The workflow will loop until the conversation is ready

Expected execution time:

First run: 2-3 minutes (OpenHands runtime initialization)
Subsequent runs: 30-60 seconds

Step 6: Verify Results

In n8n:

Click on the "Get Events" node
Check the "Output" tab
You should see events showing:
- Agent state changes
- File creation action
- Success/completion messages

On the Server:

# Check if OpenHands created the file
docker exec openhands-runtime-[conversation-id] cat /workspace/hello.txt

# Or check all runtime containers
docker ps | grep openhands-runtime

Via API:

# Get conversation ID from n8n output, then:
curl http://localhost:3000/api/conversations/[conversation-id]/events

🔧 Workflow Configuration Details

Node 1: Create Conversation

Type: HTTP Request
URL: http://172.18.0.1:3000/api/conversations
Method: POST

Body:

{
  "initial_user_msg": "Create a file named hello.txt with content: Hello from n8n automated workflow!"
}

Node 2: Wait 5s

Gives OpenHands time to start initializing

Node 3: Get Conversation Status

URL: http://172.18.0.1:3000/api/conversations/{{ $json.conversation_id }}
Method: GET
Uses conversation_id from previous node

Node 4: Check If Ready

Logic: Status is RUNNING, AWAITING_USER_INPUT, or STOPPED
True: Proceed to get events
False: Wait 10 more seconds and check again

Node 5: Get Events

URL: http://172.18.0.1:3000/api/conversations/{id}/events?limit=20
Retrieves last 20 events to see what happened

🎨 Customizing the Workflow

Change the Task:

Click on "Create Conversation" node
Under "Body Parameters"

Change initial_user_msg to your desired task:

"Run npm install && npm test && npm build"
"Clone https://github.com/user/repo and run tests"
"Create a Python script that does X"

Add Repository Support:

Add these parameters to the Create Conversation node:

{
  "initial_user_msg": "Run tests",
  "repository": "https://github.com/user/repo",
  "selected_branch": "main"
}

Increase Timeout:

Modify "Wait 10s More" node
Change amount to 15 or 20 seconds
For long-running tasks, add a maximum retry counter

🐛 Troubleshooting

Error: "Connection refused" or "Cannot reach 172.18.0.1:3000"

Check OpenHands is running:

sudo systemctl status openhands.service
curl http://localhost:3000/api/options/agents

Restart OpenHands if needed:

sudo systemctl restart openhands.service

Error: Workflow stuck in "STARTING" status

This is normal for first run!

Runtime container is being created
Wait 2-3 minutes
Check runtime logs:

docker logs [openhands-runtime-container-name]

Error: Workflow loops forever

Add a loop counter:

Add a "Function" node before "Wait 10s More"
Add this code:

// Check static data
const retries = $workflow.staticData.retries || 0;

if (retries > 20) {
  throw new Error('Max retries exceeded (5 minutes)');
}

$workflow.staticData.retries = retries + 1;
return $input.all();

No events returned

Conversation may still be initializing

Wait longer before checking events
Check conversation status shows "RUNNING" or "STOPPED"

🚀 Next Steps

Test Successful? Move to Gitea Webhook Integration!

Once this workflow works, you can:

Replace Manual Trigger with Webhook Trigger
- Node type: "Webhook"
- URL: https://n8n.oky.sh/webhook/gitea-push
Add Gitea Webhook
- Repository → Settings → Webhooks
- Target URL: The webhook URL from n8n
- Trigger: Push events
Extract Repository Info
- Add "Set" node after webhook
- Extract: {{ $json.repository.full_name }}
- Extract: {{ $json.commits[0].message }}

Pass to OpenHands

{
  "initial_user_msg": "Clone {{ $json.repository.clone_url }}, run tests",
  "repository": "{{ $json.repository.clone_url }}",
  "selected_branch": "{{ $json.ref }}"
}

📊 Success Criteria

✅ Workflow executes without errors
✅ Conversation is created successfully
✅ Status polling works
✅ Events are retrieved
✅ File is created in workspace (verify via Docker)

🔗 Resources

Workflow JSON: /tmp/openhands-workflow.json
API Reference: /home/bam/openhands-api-reference.md
OpenHands Docs: http://localhost:3000/docs
Server Logs: sudo journalctl -u openhands.service -f

Ready to test! 🎯

Open https://n8n.oky.sh and import the workflow to get started.

7.7 KiB Raw Blame History