Repolode
Submit
jamesalmeida

jamesalmeida/agent-honeypot

A honeypot flag file that installs a checkpoint and guestbook to catch AI agents that wander onto your machine.

View on GitHub
Stars
64
Forks
8
Open issues
1
Last commit
14 days ago

What is it?

agent-honeypot places a flag.txt in locations a visiting AI agent is likely to check, such as the home directory, /etc, /tmp, and root's home. The flag is a plain-text message asking any unfamiliar agent to stop exploring, avoid secrets, fix only what it can confidently identify, and report back.

The installer also creates an append-only, world-writable guestbook at ~/guest-book.txt, where a visitor can leave a timestamped line describing who or what they are and how they got in. Your own agents, such as opencode, Claude Code, Codex, and Cursor, are listed in the flag so they are not interrupted and do not sign the guestbook.

It is a checkpoint rather than a security boundary: the flag is untrusted text and grants or revokes no permissions. Installers are provided for Linux, macOS (with an optional synthetic /flag.txt entry that requires a reboot), and Windows, where symlinks and some protected paths require an elevated PowerShell.

Key features

  • 01Installs a canonical flag.txt and symlinks it into common recon locations.
  • 02Lists your own agents in the flag so they are not interrupted.
  • 03Provides an append-only, world-writable guestbook for visitors to log themselves.
  • 04Offers an optional macOS synthetic /flag.txt entry that appears after a reboot.
  • 05Includes install and uninstall scripts for Linux, macOS, and Windows.

Use cases

  • Leaving a checkpoint on a personal development machine to see whether unknown agents probe it.
  • Adding a tripwire to a shared server or CI runner to record which agents arrive.
  • Experimenting with prompt-injection defenses for AI agents in a controlled setting.

Quick start

  1. 1

    Clone the repository

    git clone https://github.com/jamesalmeida/agent-honeypot.git
  2. 2

    Enter the project directory

    cd agent-honeypot
  3. 3

    Run the installer on Linux or macOS

    ./install.sh

Things to know

  • Nothing points an agent at the flag, so it only works if the agent happens to look in those locations.
  • The flag is a prompt-level request and a misbehaving agent can ignore it.
  • The guestbook is self-reported and world-writable, so entries are claims rather than proof.
  • Windows full installation requires an elevated PowerShell session.

In collections

Open-source AI agent frameworks & appsOpen-source Mac appsSecurity scanners, audits & threat intel tools

Topics

#ai-agents#honeypot#prompt-injection#security#macos#linux#windows#flag

FAQ

What is agent-honeypot?
A honeypot flag file that installs a checkpoint and guestbook to catch AI agents that wander onto your machine. agent-honeypot places a flag.txt in locations a visiting AI agent is likely to check, such as the home directory, /etc, /tmp, and root's home. The flag is a plain-text message asking any unfamiliar agent to stop exploring, avoid secrets, fix only what it can confidently identify, and report back.
Is agent-honeypot free to use? What license does it have?
agent-honeypot is open source under the MIT license. Check the license terms before using it in commercial products.
Is agent-honeypot still maintained?
Actively maintained. The last commit to agent-honeypot was on Oct 23, 2026.
What can I use agent-honeypot for?
Leaving a checkpoint on a personal development machine to see whether unknown agents probe it. Adding a tripwire to a shared server or CI runner to record which agents arrive. Experimenting with prompt-injection defenses for AI agents in a controlled setting.
How do I install agent-honeypot?
Clone the repository: git clone https://github.com/jamesalmeida/agent-honeypot.git Enter the project directory: cd agent-honeypot Run the installer on Linux or macOS: ./install.sh
Where can I get agent-honeypot?
The source code and installation instructions are on GitHub: https://github.com/jamesalmeida/agent-honeypot

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects