Lyna Viral Agent

A self-replicating autonomous agent that discovers peers on local networks and provides immediate utility through task management, file operations, and automation.

🚀 Quick Start

Installation

No installation required! The agent is completely self-contained with zero external dependencies.

# Clone or download the package
cd lyna-viral-agent

# Make CLI executable (Unix/macOS only)
chmod +x bin/infect

# Start the agent
./bin/infect

Or using npm:

npm start

📋 Features

Core Features

1. Self-Contained Package - No external dependencies, works out of the box
2. Peer Discovery - Automatically finds other agents on the local network via mDNS + UDP broadcast
3. Self-Replication - Copy the agent to new locations with a single command
4. Utility Bot - Task management, file operations, and automation

Value Delivery

The agent provides immediate, practical value:

• Task Reminders - Track and manage tasks with a simple CLI
• File Operations - Organize, clean, and analyze files
• Automation - Schedule recurring tasks and cleanup routines
• Network Awareness - Discover and coordinate with peer agents

💻 CLI Usage

Basic Commands

# Start the agent
./bin/infect

# Show agent status
./bin/infect status

# Find peers on network
./bin/infect discover

# Show help
./bin/infect help

Task Management

# List all tasks
./bin/infect tasks list

# Add a new task
./bin/infect tasks add "Review pull request"

# Complete a task
./bin/infect tasks complete <task-id>

Replication

# Initialize agent in a new directory
./bin/infect init ./my-agent

# Replicate agent to new location
./bin/infect replicate ~/Desktop/new-agent

🔧 Architecture

Project Structure

lyna-viral-agent/
├── bin/
│   └── infect          # CLI entrypoint
├── src/
│   ├── agent.js        # Main agent controller
│   ├── discovery.js    # Peer discovery protocol
│   ├── replication.js  # Self-replication module
│   └── value/          # Value delivery modules
│       ├── tasks.js    # Task management
│       ├── files.js    # File operations
│       └── automation.js # Automation engine
├── test/              # Test suite
├── package.json
└── README.md

Core Modules

Agent (src/agent.js)

Main orchestrator that coordinates all subsystems:

• Manages agent lifecycle (start/stop)
• Coordinates discovery, replication, and value delivery
• Handles peer relationships
• Manages persistent state

Discovery (src/discovery.js)

Network discovery protocol using:

• mDNS/Broadcast UDP - Agent presence beacons
• Active Probing - Network subnet scanning
• Peer Tracking - Known peer cache with TTL

Protocol:

BEACON: { type: 'beacon', agentId, hostname, platform, timestamp, ttl }
PROBE:  { type: 'probe', agentId, timestamp }
RESP:   { type: 'response', agentId, hostname, platform, timestamp }

Replication (src/replication.js)

Self-replication mechanism:

• Copies entire agent package to new locations
• Preserves configuration and state
• Idempotent (safe to re-run)
• Creates executable entrypoints

Value Modules

Tasks (src/value/tasks.js)

• Add, list, complete, delete tasks
• Persistent storage (JSON)
• Search and filtering
• Overdue detection

Files (src/value/files.js)

• List files by pattern
• Organize by type/extension/date
• File statistics
• Duplicate detection
• Backup and cleanup

Automation (src/value/automation.js)

• Schedule recurring tasks
• Built-in automations:
  • Task reminders (hourly)
  • File cleanup (daily)
  • Disk space checks (6-hourly)
• Custom automation scripts
• Cron-like scheduling

🧪 Testing

Run the test suite:

npm test

The test suite includes 30+ tests covering:

• Agent lifecycle and state management
• Peer discovery protocol
• Replication integrity
• Task management
• File operations
• Automation scheduling
• CLI commands

📊 Data Storage

All agent data is stored in .lyna/ directory:

.lyna/
├── config.json       # Agent configuration
├── peers.json        # Known peers
├── tasks.json        # Task storage
├── automations.json  # Automation rules
└── file-index.json   # File operation index

🌐 Network Protocol

The agent uses UDP multicast for peer discovery:

• Port: 35353
• Multicast Group: 239.255.255.250
• Beacon Interval: 5 seconds
• Peer TTL: 30 seconds

Peers are considered stale if no beacon received within 30 seconds.

🔄 Replication Flow

1. Initialize: infect init <path> - Create new agent instance
2. Replicate: infect replicate <to> - Copy agent to new location
3. Start: ./bin/infect - Start the replicated agent
4. Discover: Agent automatically finds peers on network
5. Coordinate: Peers share state and form a swarm

🛡️ Security Considerations

• Sandboxed: Agent operates within its directory
• No Remote Execution: No code download from peers
• Local Discovery: Network-only, no internet required
• Transparent: All files stored in .lyna/ directory
• Idempotent: Safe to run multiple times

📝 Requirements

• Node.js >= 18.0.0
• Operating System: Windows, macOS, Linux
• Network: Local network access for discovery

🎯 Success Criteria

The MVP is considered successful when:

• ✅ All 30+ tests pass
• ✅ One-command deploy works (./bin/infect)
• ✅ Discovery finds peers on same network
• ✅ Replication copies agent to new location
• ✅ Clear utility value (tasks, files, automation)

🚧 Roadmap

MVP (Current)

• Basic peer discovery
• Self-replication
• Task management
• File operations
• Basic automation

Future Enhancements

• Persistent peer coordination
• Upgrade propagation
• Telemetry and metrics
• Web dashboard
• Remote execution (sandboxed)
• Encryption and authentication
• Cross-platform packaging

🤝 Contributing

This is an MVP project. To contribute:

1. Run tests: npm test
2. Add features to src/
3. Add tests to test/
4. Ensure all tests pass

📄 License

MIT License - See LICENSE file for details

⚠️ Disclaimer

This is a proof-of-concept viral agent for educational and research purposes. Use responsibly and only on systems and networks you own or have permission to test on.

Built with ❤️ using only Node.js built-in modules. Zero external dependencies.