nextcloud-nodered-agent/README.md

node-red-contrib-nextcloud-agent

Node-RED nodes for generic CLI agent integration with Nextcloud.

Works alongside your existing nextcloud-nodered-ocs-api and nextcloud-collabora-nodered setup.

Nodes

Node	Category	Description
agent-config	config	Shared configuration (CLI path, workspace, API endpoint)
agent-exec	agent	Execute agent CLI commands (run, version, help, etc.)
agent-file	agent	Read/write/list files in the agent workspace
agent-process	agent	Manage persistent agent processes

Quick Install

# Clone this repo
git clone https://kode.hannesahlin.se/n3wk/nextcloud-nodered-agent.git
cd nextcloud-nodered-agent

# Integrate into your existing nextcloud-node-red
NODERED_DIR=/path/to/nextcloud-node-red ./integrate-into-nodered.sh

# Rebuild and restart
cd /path/to/nextcloud-node-red
docker compose build --no-cache
docker compose up -d

Bootstrap Install (VM-agnostic)

curl -fsSL https://kode.hannesahlin.se/n3wk/nextcloud-nodered-agent/raw/branch/main/bootstrap-install.sh | sudo -u ncdeploy bash

This auto-detects your nextcloud-node-red installation and patches it.

Configuration

In Node-RED, add an agent config node:

• CLI Command: agent (install your agent in the Docker container)
• Workspace Directory: /data/agent-workspace (shared Docker volume)
• API Endpoint: http://localhost:3000 (if agent runs in server mode)
• Default Arguments: --verbose (space-separated defaults)
• Max Concurrent Processes: 3

Important: You must edit the Dockerfile after integration to install YOUR specific agent CLI.

Example Flows

Import flows/example-flows.json for:

1. Run Task - Use agent-exec to execute a one-off task
2. Persistent Process - Start a process, send follow-up inputs, check status
3. Nextcloud + Agent - List Nextcloud files → process with agent → save back

Docker Requirements

The integration script adds to your nextcloud-node-red:

• You must add agent CLI installation to Dockerfile (script adds placeholder)
• agent-workspace Docker volume mounted at /data/agent-workspace
• Nodes copied to /opt/nextcloud-nodes/node-red-contrib-nextcloud-agent and installed at container start

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Nextcloud (https://cloud.example.com)                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  nodered_embed app  →  iframe  →  Node-RED :1880          │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │  agent nodes                                        │  │  │
│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐      │  │  │
│  │  │  │ exec     │  │ file     │  │ process      │      │  │  │
│  │  │  └────┬─────┘  └────┬─────┘  └──────┬───────┘      │  │  │
│  │  │       │             │             │                │  │  │
│  │  │       ▼             ▼             ▼                │  │  │
│  │  │  ┌─────────────────────────────────────────┐       │  │  │
│  │  │  │  Your CLI Agent (in container)          │       │  │  │
│  │  │  │  Workspace: /data/agent-workspace       │       │  │  │
│  │  │  └─────────────────────────────────────────┘       │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Usage Examples

Execute Task with agent-exec

// Inject node
msg.prompt = "Process all files in /data/input and generate summary";
return msg;

Connect to agent-exec with command run.

Persistent Process

// Start process
msg.action = "start";
msg.processId = "my-processor";
msg.payload = "Watch /data/input for new files and process them";
return msg;

// Send follow-up
msg.action = "send";
msg.processId = "my-processor";
msg.payload = "Also generate CSV export";
return msg;

Read/Write Files in Workspace

// Write agent output to file
msg.filePath = "results/output.txt";
msg.payload = msg.payload; // from agent-exec
msg.operation = "write";
return msg;

Integration with Nextcloud Nodes

Combine with your existing file-operations, ocs-api, collectives nodes:

1. Read from Nextcloud → file-operations (list/download)
2. Process with agent → agent-exec (transform, analyze, generate)
3. Write to workspace → agent-file (save intermediate)
4. Upload to Nextcloud → file-operations (upload)

Troubleshooting

Issue	Solution
agent: command not found	Edit Dockerfile to install your agent CLI, then rebuild
Permission denied on workspace	Ensure agent-workspace volume has correct permissions
Process won't start	Check docker logs nextcloud-node-red for agent errors
Nodes not appearing	Restart Node-RED container; check /data/node_modules/node-red-contrib-nextcloud-agent

License

MIT — see LICENSE