pi-ducky

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 14 Open GitHub ↗

Pi Ducky is a Raspberry Pi Zero USB Gadget project that acts as a keyboard and automatically deploys remote management tools on authorized systems. Plug it into a computer, let the setup run, and manage the machine remotely through Hermes Agent and other integrated tools.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🐤 Pi-Ducky AI Agent

> **Turn a $10 Raspberry Pi Zero W into a plug-and-play AI agent deployer.**

Plug your Pi into any PC — it automatically installs an AI agent you can control from your phone. Build projects, manage files, run commands — all from Telegram, anywhere in the world.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Platform](https://img.shields.io/badge/platform-Pi%20Zero%20W-red.svg)
![OS Support](https://img.shields.io/badge/targets-Windows%20%7C%20macOS%20%7C%20Linux-brightgreen.svg)

---

## 🎯 The Problem

You're at your office. Your boss needs a project build from your home PC **right now**. You can't remote in because nothing is set up. You wish you had an AI assistant running on that PC that you could just text.

## ✨ The Solution

**Pi-Ducky** is a USB device that deploys a complete AI agent stack on any computer in under 2 minutes:

1. **Plug** the Pi into any PC's USB port
2. **Wait** 20 seconds — it auto-types commands to install everything
3. **Unplug** and walk away

Now you can text your AI agent on Telegram:

> **You**: *"Build the frontend project in ~/work/dashboard and send me the zip"*
>
> **Agent**: *Running `npm run build`... Done! Here's your file 📎 build.zip (2.3 MB)*

---

## 🏗️ What Gets Installed

| Layer | Tool | Purpose |
|:---:|:---|:---|
| 🌐 | **[Tailscale](https://tailscale.com)** | Encrypted VPN mesh — connects all your devices |
| 🧠 | **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** | AI that runs commands, builds projects, sends files |
| 🖥️ | **[RustDesk](https://rustdesk.com)** | Full remote desktop when you need to see the screen |

## 📱 How You Use It

| Scenario | Tool |
|:---|:---|
| *"Build my project and send the zip"* | 🧠 Hermes via Telegram |
| *"What's using all my disk space?"* | 🧠 Hermes via Telegram |
| *"Start the Docker containers"* | 🧠 Hermes via Telegram |
| *"I need to debug a UI visually"* | 🖥️ RustDesk (full desktop) |

---

## 🛒 Hardware Required

| Item | Cost | Notes |
|:---|:---:|:---|
| Raspberry Pi Zero W 1.1 | ~$10 | Must be the **W** version (with Wi-Fi) |
| microSD card (8GB+) | ~$5 | Class 10 recommended |
| micro-USB data cable | ~$3 | Must be a **data** cable, not charging-only |

**Total: ~$18**

---

## 🚀 Quick Start

### 1. Flash the Pi

Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/) and flash **Raspberry Pi OS Lite (32-bit)** to your microSD. Enable SSH and configure Wi-Fi in the imager settings.

### 2. Install Pi-Ducky

SSH into your Pi and run:

```bash
git clone https://github.com/YOUR_REPO/pi-ducky.git /opt/pi-ducky
sudo bash /opt/pi-ducky/setup/first-boot.sh
```

### 3. Configure

Edit `/opt/pi-ducky/config.yaml` with your API keys, or use the web dashboard:

1. Connect to Wi-Fi: **PiDucky-Setup** (password: `piducky123`)
2. Open: **http://172.24.0.1:8080**

### 4. Deploy!

Plug the Pi into any PC's USB port. Done. 🎉

> 📖 **Detailed guide**: See [setup/README.md](setup/README.md)

---

## 🔑 Required Accounts (All Free)

| Service | What You Need | Where to Get It |
|:---|:---|:---|
| **Tailscale** | Auth key | [tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys) |
| **LLM Provider** | API key | OpenRouter / Gemini / Anthropic / OpenAI / Kimi |
| **Telegram** | Bot token + User ID | [@BotFather](https://t.me/BotFather) + [@userinfobot](https://t.me/userinfobot) |

---

## 🧠 Supported LLM Providers

| Provider | Cost | Best Model |
|:---|:---|:---|
| [OpenRouter](https://openrouter.ai) | Pay-per-use | Access to all models |
| [Google Gemini](https://aistudio.google.com) | Free tier available | gemini-2.5-flash |
| [Anthropic](https://console.anthropic.com) | Pay-per-use | claude-sonnet |
| [OpenAI](https://platform.openai.com) | Pay-per-use | gpt-4o |
| [Kimi/Moonshot](https://platform.moonshot.cn) | Free tier available | moonshot-v1-auto |

---

## 📁 Project Structure

```
pi-ducky/
├── config.example.yaml          # Configuration template
├── gadget/                      # USB HID keyboard engine
│   ├── usb_setup.sh            # configfs gadget setup
│   ├── hid_keyboard.py         # Keystroke injection library
│   └── ducky_parser.py         # DuckyScript interpreter
├── agent/                       # Deployment logic
│   ├── os_detector.py          # Target OS detection
│   └── payload_runner.py       # Main orchestrator
├── payloads/                    # OS-specific payloads
│   ├── windows.ducky
│   ├── macos.ducky
│   └── linux.ducky
├── dashboard/                   # Web management UI
│   ├── server.py               # Flask API server
│   └── static/                 # Frontend (HTML/CSS/JS)
├── services/                    # systemd unit files
└── setup/                       # Installation scripts
```

---

## ⚠️ Legal & Ethical Notice

**This tool is designed for personal productivity — managing YOUR OWN computers remotely.**

- ✅ Use on computers you own
- ✅ Use on computers you have explicit written authorization to manage
- ❌ **NEVER** use on computers you don't own or aren't authorized to access
- ❌ **NEVER** use for unauthorized access, surveillance, or malicious purposes

Using this tool on unauthorized systems is **illegal** and violates computer fraud laws in most jurisdictions.

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- [Hak5 USB Rubber Ducky](https://hak5.org/products/usb-rubber-ducky) — Original inspiration
- [P4wnP1](https://github.com/RoganDawes/P4wnP1_aloa) — Pi Zero attack platform
- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — AI agent framework
- [Tailscale](https://tailscale.com) — Zero-config VPN
- [RustDesk](https://rustdesk.com) — Open-source remote desktop
# pi-ducky
# pi-ducky

pi-ducky

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README