Riona AI Agent

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

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 app under apps/recaptcha/ (@riona/recaptcha)

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

Clone the repository:

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

Install dependencies:

This is a pnpm workspace monorepo. Install pnpm, then:

pnpm install

Set up environment variables: Copy .env.example to .env in the repo root and add your credentials. All apps read from this file.

Monorepo

This repository is a pnpm workspace with two apps and shared tooling:

Package	Path	Description
`@riona/api`	`apps/api/`	Main API, Instagram/X automation, dashboard
`@riona/recaptcha`	`apps/recaptcha/`	reCAPTCHA ML model & solver
`@riona/tsconfig`	`packages/tsconfig/`	Shared TypeScript config

pnpm install              # install all workspace deps
pnpm dev                  # run API (@riona/api)
pnpm dev:recaptcha        # run reCAPTCHA app
pnpm dev:all              # run both in parallel
pnpm --filter @riona/api <script>   # run any API script

Full layout, paths, and contributor workflow: Guides/Monorepo.md.

PostgreSQL Setup

The app uses PostgreSQL for action logs. If DATABASE_URL is not set, action logs fall back to apps/api/logs/actionLogs.json.

Option A: Docker (recommended for contributors)

pnpm 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:

pnpm db:migrate

Verify

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

Stop Docker Postgres:

pnpm db:down

Upgrading from a MongoDB fork

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

Remove MONGODB_URI / MONGODB_REQUIRED
Add DATABASE_URL and DB_REQUIRED=false (see .env.example)
Run pnpm install
Start Postgres with pnpm 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

Run the agent:

pnpm start
# or during development:
pnpm dev

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.

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.

Optional: auto-run the Instagram agent loop Set IG_AGENT_ENABLED=true in .env to run the interaction loop continuously.
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!"}'

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!"

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

Command	Description
`pnpm check`	Lint + typecheck + test + format (CI parity)
`pnpm test`	Run API test suite
`pnpm test:coverage`	Tests with coverage report
`pnpm lint`	ESLint on `apps/api`
`pnpm format`	Prettier write
`pnpm check:env`	Validate required env vars
`pnpm setup`	Setup health check
`pnpm dev`	API dev server (`@riona/api`)
`pnpm dev:recaptcha`	reCAPTCHA dev server
`pnpm dev:all`	All apps in parallel
`pnpm build`	Build all packages

Per-package: pnpm --filter @riona/api <script> or pnpm --filter @riona/recaptcha <script>.

Guides

Guides/Monorepo.md — workspace layout & commands
Guides/Instagram-Bot.md
Guides/Operations.md
Guides/API.md
Guides/Env.md
Guides/Testing.md
Guides/CI.md
Guides/Scripts.md
Guides/Training.md
Guides/FAQ.md
Guides/Logging.md

reCAPTCHA Model Integration

The reCAPTCHA app lives in apps/recaptcha/ (@riona/recaptcha):

pnpm recaptcha:dev (or pnpm --filter @riona/recaptcha dev)
pnpm recaptcha:train
pnpm recaptcha:collect
pnpm recaptcha:build
pnpm recaptcha:serve

See apps/recaptcha/README.md 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	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 apps/api/src/config/accounts.json (not committed) based on apps/api/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

apps/
  api/          @riona/api — REST API, agent loop, IG/X clients, dashboard
    src/
      Agent/      AI training, characters, schema
      client/     Instagram & X/Twitter automation
      config/     accounts, igProfile, logger, database
      routes/     Express API (api.ts)
      services/   action logs, webhooks, metrics, igChallenge
      views/      Admin dashboard HTML
    scripts/      env check, setup, DB migrate
  recaptcha/    @riona/recaptcha — TensorFlow reCAPTCHA solver
packages/
  tsconfig/     @riona/tsconfig — shared compiler base
Guides/         Documentation
docker-compose.yml
pnpm-workspace.yaml

See Guides/Monorepo.md for paths, runtime directories, and CI details.

Logging

Winston writes rotating logs to apps/api/logs/. Set LOGGER=console to log only to stdout. See Guides/Logging.md.

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.

Fork the repository.
Create a feature branch.
Install deps: pnpm install
Run checks: pnpm check
Commit your changes and open a pull request.

See CONTRIBUTING.md and Guides/Monorepo.md.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 262 Commits
.github		.github
.husky		.husky
Guides		Guides
apps		apps
packages/tsconfig		packages/tsconfig
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc.cjs		.prettierrc.cjs
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTOR_RATINGS.md		CONTRIBUTOR_RATINGS.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Folders and files

Latest commit

History

Repository files navigation

Riona AI Agent

Table of Contents

About

Overview

Quick Links

Training Inputs

Feature Summary

Planned Expansion

Installation

Monorepo

PostgreSQL Setup

Option A: Docker (recommended for contributors)

Option B: Local PostgreSQL

Verify

Upgrading from a MongoDB fork

Usage

Dashboard

Development

Guides

reCAPTCHA Model Integration

Configuration Reference

Instagram

X/Twitter

AI & APIs

Database

Logging & General

Multi-Account Support

Project Policies

Project Structure

Logging

Error Handling

Contributing

License

Stargazers

Community & Contact

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages