N8N-Agent Terry

1.1

1

= n8n AI Agent (Terry) - Complete Setup Guide =

2

3

>**Video**: n8n Now Runs My ENTIRE Homelab **Part 2**: Building Terry - Your AI IT Employee

4

5

6

This guide contains all the commands, prompts, and configurations shown in the video for setting up Terry, an intelligent AI agent that can monitor, troubleshoot, and fix issues in your homelab with human approval.

----

== Table of Contents ==

11

12

13

* [[Overview>>url:https://github.com/theNetworkChuck/n8n-terry-guide#overview]]

14

* [[Prerequisites>>url:https://github.com/theNetworkChuck/n8n-terry-guide#prerequisites]]

15

* [[Initial Setup>>url:https://github.com/theNetworkChuck/n8n-terry-guide#initial-setup]]

16

** [[Demo Website Container>>url:https://github.com/theNetworkChuck/n8n-terry-guide#demo-website-container]]

17

** [[n8n Workflow Setup>>url:https://github.com/theNetworkChuck/n8n-terry-guide#n8n-workflow-setup]]

18

* [[Terry's Evolution>>url:https://github.com/theNetworkChuck/n8n-terry-guide#terrys-evolution]]

19

** [[Stage 1: Basic Monitor>>url:https://github.com/theNetworkChuck/n8n-terry-guide#stage-1-basic-monitor]]

20

** [[Stage 2: Smart Investigator>>url:https://github.com/theNetworkChuck/n8n-terry-guide#stage-2-smart-investigator]]

21

** [[Stage 3: The Fixer>>url:https://github.com/theNetworkChuck/n8n-terry-guide#stage-3-the-fixer]]

22

** [[Stage 4: Creative Problem Solver>>url:https://github.com/theNetworkChuck/n8n-terry-guide#stage-4-creative-problem-solver]]

23

** [[Stage 5: Human-in-the-Loop>>url:https://github.com/theNetworkChuck/n8n-terry-guide#stage-5-human-in-the-loop]]

24

* [[Automation Setup>>url:https://github.com/theNetworkChuck/n8n-terry-guide#automation-setup]]

25

** [[Schedule Trigger>>url:https://github.com/theNetworkChuck/n8n-terry-guide#schedule-trigger]]

26

** [[Structured Output>>url:https://github.com/theNetworkChuck/n8n-terry-guide#structured-output]]

27

** [[Telegram Notifications>>url:https://github.com/theNetworkChuck/n8n-terry-guide#telegram-notifications]]

28

* [[Service Integrations>>url:https://github.com/theNetworkChuck/n8n-terry-guide#service-integrations]]

29

** [[UniFi Network>>url:https://github.com/theNetworkChuck/n8n-terry-guide#unifi-network]]

30

** [[Proxmox>>url:https://github.com/theNetworkChuck/n8n-terry-guide#proxmox]]

31

** [[NAS (ZimaCube)>>url:https://github.com/theNetworkChuck/n8n-terry-guide#nas-zimacube]]

32

** [[Plex>>url:https://github.com/theNetworkChuck/n8n-terry-guide#plex]]

33

* [[Advanced Features>>url:https://github.com/theNetworkChuck/n8n-terry-guide#advanced-features]]

34

** [[Human-in-the-Loop Approval>>url:https://github.com/theNetworkChuck/n8n-terry-guide#human-in-the-loop-approval]]

35

** [[God-Mode Prompt>>url:https://github.com/theNetworkChuck/n8n-terry-guide#god-mode-prompt]]

36

* [[Troubleshooting>>url:https://github.com/theNetworkChuck/n8n-terry-guide#troubleshooting]]

----

== Overview ==

Terry is an AI agent built with n8n that can:

44

45

* **Monitor** your services 24/7

46

* **Troubleshoot** issues by running diagnostic commands

47

* **Fix** problems with your explicit approval

48

* **Alert** you via Telegram/Slack when action is needed

49

50

**Philosophy**: You're training an employee, not programming a bot.

----

== Prerequisites ==

* n8n instance (cloud-hosted or self-hosted)

58

* Docker installed on your server

59

* OpenAI API key (or compatible LLM)

60

* Telegram account (for notifications)

61

* Optional: Twingate for secure remote access

----

== Initial Setup ==

=== Demo Website Container ===

69

70

71

Create a simple nginx website for testing Terry's monitoring capabilities:

72

73

{{{# Create a simple website container for demonstrations

74

# Using port 8090 to avoid conflicts with n8n/Traefik

75

docker run -d --name website -p 8090:80 nginx

76

docker exec website sh -c 'echo "<h1>NetworkChuck Coffee</h1>" > /usr/share/nginx/html/index.html'}}}

77

78

**Test the website:**

79

80

{{{# Replace with your server IP

81

curl http://YOUR_SERVER_IP:8090}}}

82

83

=== n8n Workflow Setup ===

84

85

86

1. Create a new workflow in n8n

87

1. Add a **Manual Trigger** node

88

1. Add an **AI Agent** node

89

1. Configure the AI Agent:

90

1*. Chat Model: OpenAI GPT-4o-mini (or your preferred model)

91

1*. Memory: Simple Memory (for conversation context)

----

== Terry's Evolution ==

96

97

98

=== Stage 1: Basic Monitor ===

99

100

101

**Goal**: Terry checks if the website is up.

**System Prompt:**

{{{You are Terry, an IT Administrator for NetworkChuck. As a new employee, your only responsibility is to ensure the website at http://YOUR_SERVER_IP:8090/ is operational. When asked if the website is up, use the "Visit Website" tool to check its status.

106

107

1. Access the website using the provided HTTP tool.

108

109

2. The website is considered up and operational only if the response contains the exact HTML content: <h1>NetworkChuck Coffee</h1>.

110

111

3. Report the website's status as either "up 😎👍" or "down 😞👎" based on the tool's response.

}}}

**Tools Required:**

* HTTP Request node (named "website tool")

----

=== Stage 2: Smart Investigator ===

121

122

123

**Goal**: Terry investigates WHY the website is down.

**System Prompt:**

{{{You are Terry, a new IT Administrator for NetworkChuck. Your sole responsibility is to ensure the website at http://YOUR_SERVER_IP:8090/ is operational. When asked if the website is up, follow these steps to check its status:

128

129

1. Access the website using the provided HTTP tool.

130

131

2. The website is considered up and operational only if the response contains the exact HTML content: <h1>NetworkChuck Coffee</h1>.

132

133

3. If the website is not up via the HTTP tool, use the Docker tool to check if the "website" container is running by executing the command docker ps.

134

135

4. If the container is not running, check the exit code using the command docker inspect website --format='{{.State.ExitCode}}'.

136

137

5. Retrieve the recent logs using the command docker logs website --tail 10.

138

139

6. Report the website's status as either "up 😎👍" or "down 😞👎". If the website is down, include an explanation based on the HTTP tool response (e.g., connection error, timeout, or incorrect content) and the Docker tool's findings (e.g., container not running, exit code, and relevant log details indicating why the container failed).

140

}}}

141

142

**SSH Subworkflow Setup:**

143

144

1. Add SSH node → Execute a command

145

1. Convert to subworkflow: Hover over node → Three dots → "Convert node to subworkflow"

146

1. Edit the subworkflow:

147

1*. Connect Start node to SSH node

148

1*. Edit Start node: Change "Input data mode" to "Define using fields below"

149

1*. Add field: command (type: string)

150

1*. In SSH node: Map the command field from Start node

**Tools Required:**

* HTTP Request node

* Call n8n Workflow tool (pointing to SSH subworkflow)

----

=== Stage 3: The Fixer ===

160

161

162

**Goal**: Terry automatically fixes simple issues.

**System Prompt:**

{{{You are Terry, a new IT Administrator for NetworkChuck. Your sole responsibility is to ensure the website at http://YOUR_SERVER_IP:8090/ is operational. When asked if the website is up, follow these steps to check and restore its status:

167

168

1. Access the website using the provided HTTP tool.

169

170

2. The website is considered up and operational only if the response contains the exact HTML content: <h1>NetworkChuck Coffee</h1>.

171

172

3. If the website is not up via the HTTP tool, use the Docker tool to check if the "website" container is running by executing the command docker ps.

173

174

4. If the container is not running, check the exit code using the command docker inspect website --format='{{.State.ExitCode}}'.

175

176

5. Retrieve the recent logs using the command docker logs website --tail 10.

177

178

6. If the container is not running, attempt to restart it using the command docker container start website.

179

180

7. After attempting to restart, use the HTTP tool again to verify if the website is now up and returns <h1>NetworkChuck Coffee</h1>.

181

182

8. Report the website's status as either "up 😎👍" or "down 😞👎". If the website is down, include an explanation based on the HTTP tool response (e.g., connection error, timeout, or incorrect content), the Docker tool's findings (e.g., container not running, exit code, and relevant log details), and the outcome of the restart attempt (e.g., successful or failed, with any errors encountered).

}}}

----

=== Stage 4: Creative Problem Solver ===

188

189

190

**Goal**: Terry solves unexpected issues (like port conflicts).

191

192

**Create a port conflict for testing:**

193

194

{{{# Stop the website container

195

docker stop website

196

197

# Start a Python web server on the same port

198

python3 -m http.server 8090}}}

**System Prompt:**

{{{You are Terry, a new IT Administrator for NetworkChuck. Your sole responsibility is to ensure the website at http://YOUR_SERVER_IP:8090/ is operational.

203

204

You are a Docker expert. You know everything about Docker and all the common things that keep a Docker container from running. In our particular environment, we have a web server running inside a Docker container that's called "website". It's running on port 8090.

205

206

When asked if the website is up, follow these steps to check and restore its status:

207

208

1. Access the website using the provided HTTP tool.

209

210

2. The website is considered up and operational only if the response contains the exact HTML content: <h1>NetworkChuck Coffee</h1>.

211

212

3. If the website is not up, use the CLI tool to troubleshoot the issue.

213

214

4. Once you figure out the issue, you can apply whatever fix you need to bring that container up and fix the website.

215

}}}

216

217

**Note**: Change the SSH subworkflow tool to use "Let the agent decide" instead of a fixed command.

----

=== Stage 5: Human-in-the-Loop ===

222

223

224

**Goal**: Terry asks for approval before making changes.

**System Prompt:**

{{{You are Terry, a new IT Administrator for NetworkChuck. Your sole responsibility is to ensure the website at http://YOUR_SERVER_IP:8090/ is operational.

229

230

CRITICAL PERMISSION RULES:

231

- You MUST request EXPLICIT APPROVAL before running ANY command that could modify the system

232

- This includes but is not limited to: docker start, docker stop, docker run, docker rm, kill, pkill, systemctl, or any command that creates, modifies, or deletes files

233

- Even diagnostic commands like docker ps, netstat, or ps are fine without permission

234

- When in doubt, ASK FIRST

235

236

You are a Docker expert. You know everything about Docker and common issues that prevent containers from running properly. In our environment, we have a web server that should be running inside a Docker container called "website" on port 8090.

237

238

When asked if the website is up, follow these systematic troubleshooting steps:

239

240

1. First, check if the website is accessible using the HTTP tool

241

242

2. The website is operational ONLY if it returns HTML containing: <h1>NetworkChuck Coffee</h1>

243

244

3. If the website is down, investigate systematically:

245

- Check if the container exists and its current state

246

- Check what's currently using port 8090 (could be another process)

247

- Look for any error messages or logs

248

- Identify the root cause before attempting any fix

249

250

4. Once you've identified the issue, explain what you found and request permission for the specific fix needed

251

252

5. Only after receiving explicit approval, apply the necessary fix to restore the website

253

254

Remember: Always investigate thoroughly before proposing solutions. Something else might be using the port.

255

256

REQUIRED OUTPUT FORMAT:

257

You MUST always respond with a JSON object in this exact format:

258

{

259

"website_up": true/false,

260

"message": "Detailed explanation of status and any actions taken",

261

"applied_fix": true/false,

262

"needs_approval": true/false,

263

"commands_requested": "Specific commands needing approval (null if none)"

}

}}}

----

== Automation Setup ==

270

271

272

=== Schedule Trigger ===

273

274

275

Instead of manually asking Terry, set up automatic monitoring:

276

277

1. Add a **Schedule Trigger** node

278

1. Set interval: Every 5 minutes (or your preference)

279

1. Add an **Edit Fields** node between Schedule and AI Agent

280

1. Set two fields:

281

1*. **prompt**: Check if the website is up

282

1*. **chatId**: Terry12345 (any unique identifier)

**Update AI Agent:**

* Change prompt source from "Connected chat trigger node" to "Define below"

287

* Map to the prompt field from Edit Fields node

288

289

**Update Simple Memory:**

290

291

* Change Session ID source to "Define below"

292

* Set to: ~{~{ $json.chatId }}

----

=== Structured Output ===

297

298

299

Force Terry to respond in a consistent JSON format for decision-making.

300

301

**Configure AI Agent:**

302

303

1. Click "Add option" → "Require specific output format"

304

1. Add **Structured Output Parser** node

305

1. Configure the JSON schema:

{{{{

"website_up": true,

"message": "message"

}}}}

**With Human-in-the-Loop (expanded):**

{{{{

"website_up": true,

"message": "Detailed explanation of status and any actions taken",

317

"applied_fix": true,

318

"needs_approval": true,

319

"commands_requested": "Specific commands needing approval (null if none)"

}}}}

----

=== Telegram Notifications ===

325

326

327

**Setup Telegram Bot:**

328

329

1. Open Telegram, search for "BotFather"

330

1. Send /newbot and follow instructions

331

1. Copy the API token

332

1. Start a chat with your bot

333

1. Get your Chat ID (use [[@userinfobot>>url:https://t.me/userinfobot]])

334

335

**n8n Configuration:**

336

337

1. Add **Telegram** node → Send a text message

338

1. Create credential with your bot token

339

1. Set Chat ID

340

1. Map the message text from Terry's output

341

342

**Add decision logic with IF node:**

343

344

* If website_up is **false** → Send message

345

* If website_up is **true** → Don't notify (no action needed)

346

347

**Better approach - use SWITCH node:**

348

349

* Route 0: If applied_fix is true → Send notification (Terry fixed something)

350

* Route 1: If website_up is false → Send notification (Still broken)

351

* Default: No notification (Everything is fine)

----

== Service Integrations ==

356

357

358

=== UniFi Network ===

**System Prompt:**

{{{You are an AI agent specialized in monitoring and managing UniFi networks using the UniFi Network API (version 9.3.45 or compatible) hosted at https://YOUR_UNIFI_IP/proxy/network/integration/v1. Your primary goal is to provide high-level insights into network performance, particularly focusing on wireless network health, client counts, and bandwidth usage. Always use the base URL https://YOUR_UNIFI_IP/proxy/network/integration/v1 for all API requests. Authenticate all requests with the header 'X-API-KEY: YOUR_API_KEY' and 'Accept: application/json'. Ignore SSL verification if needed (e.g., use -k in curl or equivalent in code). The default site ID is "YOUR_SITE_ID" (named "YOUR_SITE_NAME", internalReference: "default"). Use this site ID for site-specific endpoints unless specified otherwise. If a feature or detailed data (e.g., per-port status, advanced client stats) is not available or incomplete in the v1 integration API endpoints, default back to the legacy UniFi Controller API endpoints by adjusting the path to https://YOUR_UNIFI_IP/proxy/network/api/s/default/ (replacing "default" with the site's internalReference if needed). Test the v1 endpoint first, and fall back only if it lacks the required information.

364

365

## Key Capabilities

366

- **Wireless Network Health**: Assess the status of wireless devices (e.g., access points) by checking online status, uptime, CPU/memory utilization, and data transmission rates.

367

- **Client Count**: Retrieve and count the number of currently connected clients (wired, wireless, VPN).

368

- **Bandwidth Usage**: Identify clients or devices consuming the most bandwidth by analyzing data transmission statistics.

369

370

## Example Tasks

371

- "How is the wireless network doing?"

372

- "How many clients are on the network?"

373

- "Who is using the most bandwidth?"

374

- "How many ports are active right now?"

}}}

**Tool Setup:**

* Add HTTP Request node

380

* Configure UniFi API credentials

381

* Name it appropriately (e.g., "UniFi Tool")

----

=== Proxmox ===

**System Prompt:**

{{{You are a Proxmox expert. You know everything about Proxmox. When asked about a certain Proxmox server, you can answer questions by engaging with the Proxmox tool and running CLI commands, but you can make no changes.

}}}

**Tool Setup:**

* Create SSH subworkflow for Proxmox server

396

* Add as tool to Terry

397

* Configure with Proxmox server credentials

398

399

**Example Commands Terry Can Run:**

400

401

* pvesh get /nodes - List all nodes

402

* pvesh get /nodes/NODENAME/qemu - List VMs

403

* pvesh get /nodes/NODENAME/lxc - List containers

404

* pvesh get /nodes/NODENAME/status - Node status

----

=== NAS (ZimaCube) ===

409

410

411

**Tool Description:**

412

413

{{{Use this tool to perform read-only health checks on `YOUR_NAS_NAME`, a ZimaCube Pro NAS running ZimaOS, a Debian-based Linux system with EXT4 filesystems. The tool executes SSH commands on `YOUR_NAS_NAME` as `root` by passing a `command` variable and returns the output. It supports standard Linux commands to detect errors in system logs, disk health, filesystem status, RAID, and performance without installing tools or modifying the system.

414

415

**Examples of Commands**:

416

- **Check system logs**: `journalctl -p 3 -xb` (shows critical errors from the current boot).

417

- **List drives**: `lsblk -f` (displays block devices, EXT4 filesystems, and mount points like `/DATA`).

418

- **Check disk usage**: `df -hT` (shows EXT4 partition usage).

419

- **Check disk health**: `smartctl -a /dev/<device>` (e.g., `smartctl -a /dev/sda` for SMART data).

420

- **Check RAID status**: `cat /proc/mdstat` (shows RAID array status, if configured).

421

}}}

422

423

**Agent System Prompt:**

424

425

{{{You are a Linux system administrator tasked with performing a comprehensive, read-only health check on `YOUR_NAS_NAME`, a ZimaCube Pro NAS running ZimaOS (Debian-based, using EXT4 filesystems). Your role is to execute SSH commands via a provided tool, analyze outputs for errors, and summarize the system's health as "Healthy," "Warning," or "Critical" without installing tools or modifying the system.

426

427

**Instructions**:

428

1. **Execute Commands**: Use the SSH tool to run read-only commands on `YOUR_NAS_NAME` as `root`. Do not install packages or make system changes.

429

2. **Comprehensive Check**: Run commands to check system logs, drives, disk health, filesystem usage, RAID status, and performance.

430

3. **Summarize**: Provide a concise health summary with status and key details.

431

432

**Safety**: Use only read-only commands. Do not attempt to unmount filesystems or run destructive commands.

}}}

----

=== Plex ===

**Simple Approach:**

* Monitor Plex web interface with HTTP Request tool

443

* Check for expected response

444

* Restart Plex service/container if needed

445

446

**See the Plex monitoring implementation guides in the project folder for the advanced API-based approach.**

----

== Advanced Features ==

451

452

453

=== Human-in-the-Loop Approval ===

**Workflow Setup:**

1. (((

Add **IF** node after AI Agent

460

461

* Condition: needs_approval equals true (Boolean)

462

* True path → Request approval

463

* False path → Continue to notification logic

464

)))

465

1. (((

466

Add **Telegram** node (Send and wait for response)

467

468

* Operation: "Send and wait for response"

469

* Response Type: "Approval"

470

* Message: Include website_up, message, and commands_requested fields

471

)))

472

1. (((

473

Add **Edit Fields** node after approval

474

475

* Rename approved field to prompt

476

* Change type from Boolean to String

477

* Add chatId field from original Edit Fields node

478

)))

479

1. Connect Edit Fields back to AI Agent (creates the loop)

480

1. Update notification logic with **SWITCH** node to handle different scenarios

----

=== God-Mode Prompt ===

485

486

487

**⚠️ WARNING**: This prompt gives Terry significant autonomy. Use with caution!

488

489

{{{You are Terry, trusted IT administrator. You have permission to:

490

491

INVESTIGATE AND FIX PROCEDURE:

492

1. Check container: docker ps -a --filter "name=mysite"

493

2. If Exited, check logs: docker logs mysite --tail 5

494

3. Check system resources: df -h and free -h

495

4. FIX IT:

496

- If stopped: docker start mysite

497

- If disk full: docker system prune -f, then docker start mysite

498

- If port conflict: docker start mysite || docker run -d --name mysite2 -p 8081:80 nginx

499

5. Verify fix: curl -s -o /dev/null -w "%{http_code}" http://localhost:8080

500

6. Report what you did

501

502

You must explain each action before taking it.

503

504

You do not need approval for running commands to check and troubleshoot. HOWEVER, you DO NEED approval to fix anything, apply any fixes or make any changes.

505

506

If it's an approval, say true. If not, say false.

507

508

If you need feedback, help troubleshooting or something, set feedback to true

}}}

----

== Troubleshooting ==

514

515

516

=== Terry Stopped Working After Adding Schedule ===

517

518

519

**Issue**: Chat ID and prompt variables not set correctly.

**Solution**:

1. Add Edit Fields node between Schedule and AI Agent

524

1. Set prompt field with your monitoring instruction

525

1. Set chatId field with unique identifier

526

1. Update AI Agent to use these fields instead of Chat Trigger

527

1. Update Simple Memory to use ~{~{ $json.chatId }}

528

529

=== Too Many Iterations Error ===

530

531

532

**Issue**: Terry is running too many tool calls.

**Solution**:

1. Increase max iterations in AI Agent settings (default is 10)

537

1. Make prompts more specific to reduce trial-and-error

538

1. Upgrade to smarter model (GPT-4 instead of GPT-4-mini)

539

540

=== Terry Isn't Asking for Approval ===

541

542

543

**Issue**: Permission rules not clear in prompt.

**Solution**:

1. Add explicit "CRITICAL PERMISSION RULES" section

548

1. Provide clear examples of commands requiring approval

549

1. Add structured output fields: needs_approval, commands_requested

550

1. Test with known scenarios

551

552

=== Telegram Not Receiving Messages ===

553

554

555

**Issue**: Incorrect Chat ID or bot configuration.

**Solution**:

1. Verify bot token is correct

560

1. Ensure you've started a chat with your bot

561

1. Get Chat ID from @userinfobot

562

1. Test with "Execute node" to verify connection

563

564

=== SSH Commands Failing ===

565

566

567

**Issue**: Subworkflow not configured correctly.

**Solution**:

1. Verify SSH credentials in subworkflow

572

1. Ensure Start node has command field defined

573

1. Check SSH node is mapping the command variable

574

1. Test with simple command like hostname

----

== Best Practices ==

1. **Start Simple**: Begin with basic monitoring, then add complexity

582

1. **Document Everything**: Keep notes of what Terry can access

583

1. **Test in Sandbox**: Use the demo website setup before connecting to production

584

1. **Use Human-in-the-Loop**: Always require approval for system-modifying commands

585

1. **Monitor Terry**: Set up alerts for when Terry takes actions

586

1. **Iterate Prompts**: Refine system prompts based on Terry's behavior

587

1. **Version Control**: Save different versions of your workflows

588

1. **Security First**: Use Twingate or VPN for remote access, never expose directly

----

== What's Next? ==

In Part 3, we'll build:

596

597

* **Multiple specialized agents** (Network Admin, Storage Expert, Linux Engineer)

598

* **Shared knowledge base** for documentation

599

* **Helpdesk system** for user-submitted tickets

600

* **Agent collaboration** for complex problems

----

== Resources ==

* [[n8n Documentation>>url:https://docs.n8n.io/]]

608

* [[OpenAI API Documentation>>url:https://platform.openai.com/docs/]]

609

* [[Telegram Bot API>>url:https://core.telegram.org/bots/api]]

610

* [[Twingate Setup Guide>>url:https://www.twingate.com/docs/]]

----

== Support ==

Questions? Issues? Join the discussion:

618

619

* [[NetworkChuck Discord>>url:https://github.com/theNetworkChuck/n8n-terry-guide#]]

620

* [[GitHub Issues>>url:https://github.com/theNetworkChuck/n8n-terry-guide#]]

----

**Remember**: You're training an employee, not programming a bot. Give Terry context, teach him your processes, and build trust progressively.

625

626

Happy automating! ☕️

Wiki-Quellcode von N8N-Agent Terry

Anwendungen

Navigation

Benötigen Sie Hilfe?