mvp-factory-setups/n8n-workflow-setup-guide.md

# 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

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

---

### Step 2: Import the Workflow

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

**Alternative: Manual Copy-Paste**
If file upload doesn't work:
1. Copy the contents of `/tmp/openhands-workflow.json`
2. In n8n, click "⋮" menu → "Import from URL or File"
3. Paste the JSON directly
4. 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

1. Click **"Save"** (top right) to save the workflow
2. Give it a name: **"OpenHands API Test"**
3. Click **"Execute Workflow"** button (top right)
4. 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

1. Watch the workflow execute in real-time
2. Each node will light up green as it completes
3. Click on any node to see its output data
4. 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:
1. Click on the **"Get Events"** node
2. Check the **"Output"** tab
3. You should see events showing:
   - Agent state changes
   - File creation action
   - Success/completion messages

#### On the Server:
```bash
# 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:
```bash
# 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:**
  ```json
  {
    "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:
1. Click on **"Create Conversation"** node
2. Under **"Body Parameters"**
3. 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:
```json
{
  "initial_user_msg": "Run tests",
  "repository": "https://github.com/user/repo",
  "selected_branch": "main"
}
```

### Increase Timeout:
1. Modify **"Wait 10s More"** node
2. Change amount to 15 or 20 seconds
3. 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:**
```bash
sudo systemctl status openhands.service
curl http://localhost:3000/api/options/agents
```

**Restart OpenHands if needed:**
```bash
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:
```bash
docker logs [openhands-runtime-container-name]
```

### Error: Workflow loops forever

**Add a loop counter:**
1. Add a **"Function"** node before "Wait 10s More"
2. Add this code:
```javascript
// 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:

1. **Replace Manual Trigger with Webhook Trigger**
   - Node type: "Webhook"
   - URL: `https://n8n.oky.sh/webhook/gitea-push`

2. **Add Gitea Webhook**
   - Repository → Settings → Webhooks
   - Target URL: The webhook URL from n8n
   - Trigger: Push events

3. **Extract Repository Info**
   - Add "Set" node after webhook
   - Extract: `{{ $json.repository.full_name }}`
   - Extract: `{{ $json.commits[0].message }}`

4. **Pass to OpenHands**
   ```json
   {
     "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.