Riona AI Agent

GitHub stars GitHub forks GitHub license GitHub issues GitHub contributors PRs Welcome Code style: Prettier

Website | Roadmap | Twitter | Contact

Table of Contents

• About
• Overview
• Quick Links
• Feature Summary
• Planned Expansion
• Installation
• PostgreSQL Setup
• Usage
• Dashboard
• Development
• Guides
• reCAPTCHA Model
• Configuration Reference
• Contributing
• License
• Community & Contact
• Multi-Account Support
• Project Policies
• Project Structure
• Logging
• Error Handling
• Stargazers

About

Riona AI Agent is an AI-powered social automation platform for Instagram and X/Twitter. It combines browser automation, AI-generated content, account workflows, scheduling, engagement actions, and training inputs so you can run a social media operator from one codebase.

Overview

Riona is built to automate social activity while keeping control surfaces explicit. The project includes:

• Instagram automation for login, posting, liking, commenting, messaging, and follower scraping
• X/Twitter support in progress for publishing and engagement workflows
• AI content generation using Gemini for captions and comments
• Training inputs from YouTube, audio, files, and websites
• API endpoints, health checks, dashboards, cooldowns, summaries, and logging
• A separate reCAPTCHA ML subproject under riona-recaptcha-model/

Quick Links

• Live website: https://www.agentriona.xyz
• Project roadmap: ROADMAP.md
• CA: AuTUKS9PCP8YQuBdqSXfBRoz79USEKX8EnTkx6Wnpump

If you'd like to support the project, see the private donations file maintained locally.

Training Inputs

Before running automation, you can shape the agent with:

• YouTube video URLs
• Audio files
• Portfolio or website links
• Documents and text files including PDF, DOC, DOCX, and TXT

Feature Summary

• Instagram automation with cookies, relogin handling, posting, scheduling, and interactions
• AI-generated captions and comments with schema-guided responses
• Multi-account and profile-based operation support
• PostgreSQL-backed action logs, summaries, and optional persistence
• Simple dashboard for runtime health and latest activity
• Logging, environment validation, and utility scripts for operations

Planned Expansion

• Complete X/Twitter workflow coverage
• GitHub automation
• Additional analytics, reporting, and compliance controls

Installation

1. Clone the repository:

 git clone https://github.com/david-patrick-chuks/riona-ai-agent.git
 cd riona-ai-agent

2. Install dependencies:

 npm install

3. Set up environment variables: Rename the .env.example file to .env in the root directory and add your Instagram credentials. Refer to the .env.example file for the required variables.

PostgreSQL Setup

The app uses PostgreSQL for action logs. If DATABASE_URL is not set, action logs fall back to a local JSON file (logs/actionLogs.json).

Option A: Docker (recommended for contributors)

npm run db:up

This starts PostgreSQL on port 5432 with credentials that match .env.example.

Option B: Local PostgreSQL

Install PostgreSQL locally, create a database, and point .env at it:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/riona_ai_agent

Create the database if needed:

createdb riona_ai_agent

Schema is applied automatically on startup. To run migrations manually:

npm run db:migrate

Verify

docker compose ps
# or
psql "$DATABASE_URL" -c '\dt'

Stop Docker Postgres:

npm run db:down

Upgrading from a MongoDB fork

If your fork still uses MONGODB_URI, merge this branch and update .env:

1. Remove MONGODB_URI / MONGODB_REQUIRED
2. Add DATABASE_URL and DB_REQUIRED=false (see .env.example)
3. Run npm install (mongoose removed, pg added)
4. Start Postgres with npm run db:up or use your local instance

No data migration script is provided — MongoDB action logs were optional and the app still works without a database.

Usage

1. Run the agent:

npm start

This starts the API server on port 3000 and opens the dashboard at http://localhost:3000/dashboard. The Instagram browser only launches when you log in or trigger interactions — it does not auto-comment on its own unless IG_AGENT_ENABLED=true.

2. Log in and trigger interactions:

curl -X POST http://localhost:3000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_IG_USERNAME","password":"YOUR_IG_PASSWORD"}'

Then open the dashboard or call POST /api/interact with your session cookie to start liking and commenting on feed posts.

3. Optional: auto-run the Instagram agent loop Set IG_AGENT_ENABLED=true in .env to run the interaction loop continuously.
4. Post a photo (by URL)

 curl -X POST http://localhost:3000/api/post-photo \\
   -H "Content-Type: application/json" \\
   --cookie "token=YOUR_JWT_TOKEN" \\
   -d '{"imageUrl":"https://example.com/photo.jpg","caption":"Hello IG!"}'

5. Post a photo (file upload)

 curl -X POST http://localhost:3000/api/post-photo-file \\
   -H "Content-Type: multipart/form-data" \\
   --cookie "token=YOUR_JWT_TOKEN" \\
   -F "image=@/path/to/photo.jpg" \\
   -F "caption=Hello IG!"

6. Schedule a photo post

 curl -X POST http://localhost:3000/api/schedule-post \\
   -H "Content-Type: application/json" \\
   --cookie "token=YOUR_JWT_TOKEN" \\
   -d '{"imageUrl":"https://example.com/photo.jpg","caption":"Scheduled post","cronTime":"0 9 * * *"}'

Dashboard

Open http://localhost:3000/dashboard for live status, the last IG run summary, recent actions, application logs, and errors.

Development

• Run tests: npm test
• Lint: npm run lint
• Format: npm run format
• Env check: npm run check:env
• Setup check: npm run setup

Guides

• Guides/Instagram-Bot.md
• Guides/Operations.md
• Guides/API.md
• Guides/Env.md
• Guides/Testing.md
• Guides/CI.md
• Guides/FAQ.md
• Guides/Logging.md
• Guides/Scripts.md
• Guides/Training.md

reCAPTCHA Model Integration

This repo now includes the reCAPTCHA model under riona-recaptcha-model/ and is run via root scripts:

• npm run recaptcha:dev
• npm run recaptcha:train
• npm run recaptcha:collect
• npm run recaptcha:build
• npm run recaptcha:serve

See the separate riona-recaptcha-model README for more details.

Configuration Reference

Instagram

Variable	Type	Default	Description
IGusername	string		Instagram username
IGpassword	string		Instagram password
IG_RUN_PROFILE	string	standard	Run profile: safe, standard, aggressive
IG_AGENT_ENABLED	boolean	false	Auto-run Instagram agent loop
IG_AGENT_INTERVAL_MS	number	30000	Agent loop interval in ms
IG_DAILY_MAX_ACTIONS	number	0	Daily max IG actions (0 = unlimited)
IG_MAX_POSTS_PER_RUN	number		Max posts per run (overrides profile)
IG_ACTION_DELAY_MIN_MS	number		Min action delay (overrides profile)
IG_ACTION_DELAY_MAX_MS	number		Max action delay (overrides profile)
IG_COOLDOWN_MINUTES	number		Cooldown duration in minutes
IG_COMMENT_ALLOWLIST	string		Comma-separated allowed comment terms
IG_COMMENT_DENYLIST	string		Comma-separated blocked comment terms
IG_COMMENT_SENTIMENT	string	any	Sentiment filter: any, positive, neutral
IG_COMMENT_MIN_LENGTH	number		Minimum allowed comment length (chars)
IG_COMMENT_MAX_LENGTH	number		Maximum allowed comment length (chars)
IG_AD_MARKERS	string	sponsored,paid partnership,paid partnership with	Comma-separated ad markers
IG_AD_BUTTON_MARKERS	string	learn more,shop now,sign up,install now,get offer,subscribe,book now	Comma-separated ad button markers

X/Twitter

Variable	Type	Default	Description
Xusername	string		X/Twitter username
Xpassword	string		X/Twitter password

AI & APIs

Variable	Type	Default	Description
GEMINI_API_KEY	string		Primary Gemini API key
GEMINI_API_KEY_1	string		Secondary Gemini API key
GEMINI_API_KEY_2	string		Tertiary Gemini API key

Database

Variable	Type	Default	Description
DATABASE_URL	string		PostgreSQL connection URL
DB_REQUIRED	boolean	false	Require PostgreSQL connection (exit if missing)

Logging & General

Variable	Type	Default	Description
LOGGER	string	console	Logging backend: winston or console

Multi-Account Support

Create src/config/accounts.json (not committed) based on src/config/accounts.example.json. Then pass account in /api/login to select which account to use.

Project Policies

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• LICENSE

Project Structure

• src/client: Contains the main logic for interacting with social media platforms like Instagram.
• src/config: Configuration files, including the logger setup.
• src/utils: Utility functions for handling errors, cookies, data saving, etc.
• src/Agent: Contains the AI agent logic and training scripts.
• src/Agent/training: Training scripts for the AI agent.
• src/Agent/schema: Schema definitions for AI-generated content and database models.
• src/test: Contains test data and scripts, such as example tweets.

Logging

The project uses a custom logger to record information, warnings, and errors. Logs are stored in the logs/ directory.

Error Handling

Process-level error handlers are set up to catch unhandled promise rejections, uncaught exceptions, and process warnings. Errors are logged using the custom logger.

Contributing

Contributions are welcome and appreciated.

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Push your changes to your fork.
5. Open a pull request for review.

Please ensure your changes follow the existing code style and include documentation updates when necessary.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Stargazers

Thank you to all our supporters!

Star History Chart

Built with ❤️ by David Patrick

Community & Contact

• GitHub Discussions: use the Discussions tab for Q&A
• Issues: bug reports and feature requests
• Twitter: @david_patrick01
• Email: davidchuksdev@gmail.com

Real-time community chat is not available yet. If there is sufficient interest, a Discord server may be created in the future. Feel free to open a discussion to express interest.